docs: add mermaid diagrams to documentation

Add accurate Mermaid diagrams that GitHub renders natively:

- ARCHITECTURE.md: component/dependency diagram (cmd -> controller
  -> aid/dao/view -> go-tfe -> TFC API, with credentials.yaml and
  TFC_* env vars feeding token/org resolution) and a sequence diagram
  for `tecli workspace create`.
- README.md: high-level request-flow overview diagram.

All mermaid diagrams validated locally with mermaid-cli (3 blocks, 0 failures).

Author: valter-silva-au

ARCHITECTURE.md

@@ -12,9 +12,39 @@ The command framework is [Cobra](https://github.com/spf13/cobra). Configuration
 
 The dependency direction flows in one direction, from the command adapters down to the API client:
 
-```text
-cobra/cmd  -->  cobra/controller  -->  cobra/aid  -->  helper/, box/
-                                  -->  hashicorp/go-tfe
+```mermaid
+%% Component and dependency diagram
+flowchart TB
+    user([You / CI pipeline])
+
+    subgraph cli["tecli binary"]
+        main["main.go<br/>cmd.Execute()"]
+        cmd["cobra/cmd<br/>thin command adapters"]
+        controller["cobra/controller<br/>business logic, PreRunE / RunE"]
+        aid["cobra/aid<br/>flag builders, TFE client, Viper"]
+        dao["cobra/dao<br/>resolve org and tokens"]
+        view["cobra/view<br/>interactive prompts"]
+        helperbox["helper/, box/<br/>utilities and embedded manuals"]
+    end
+
+    gotfe["hashicorp/go-tfe<br/>Go client"]
+    tfc[("Terraform Cloud / Enterprise API")]
+
+    creds["credentials.yaml<br/>under os.UserConfigDir()"]
+    env["TFC_* environment variables"]
+
+    user --> cmd
+    main --> cmd
+    cmd --> controller
+    controller --> aid
+    controller --> dao
+    controller --> view
+    controller --> gotfe
+    aid --> helperbox
+    aid --> gotfe
+    dao --> creds
+    env --> dao
+    gotfe --> tfc
 ```
 
 Layers below `controller` do not import `cmd`. Layers below `aid` do not import `controller`.
@@ -46,6 +76,37 @@ A single command, such as `tecli workspace list`, flows through the layers:
 4. `RunE` reads the resolved token through `cobra/dao` (environment variable first, then the active profile), builds a `*tfe.Client` with `aid.GetTFEClient`, and calls the matching `go-tfe` method.
 5. The controller prints the API response as JSON.
 
+The following sequence shows `tecli workspace create --name my-workspace`:
+
+```mermaid
+%% Sequence for tecli workspace create
+sequenceDiagram
+    actor User
+    participant Cmd as cobra/cmd
+    participant Ctrl as cobra/controller
+    participant Aid as cobra/aid
+    participant Dao as cobra/dao
+    participant Tfe as hashicorp/go-tfe
+    participant TFC as Terraform Cloud API
+
+    User->>Cmd: tecli workspace create --name my-workspace
+    Cmd->>Ctrl: run matched command (initConfig loads Viper)
+    Ctrl->>Ctrl: PreRunE validates argument and --name flag
+    Ctrl->>Dao: GetOrganizationToken(profile)
+    Dao-->>Ctrl: token (TFC_* env var, else profile)
+    Ctrl->>Aid: GetTFEClient(token)
+    Aid-->>Ctrl: *tfe.Client
+    Ctrl->>Dao: GetOrganization(profile)
+    Dao-->>Ctrl: organization
+    Ctrl->>Aid: GetWorkspaceCreateOptions(cmd)
+    Aid-->>Ctrl: tfe.WorkspaceCreateOptions
+    Ctrl->>Tfe: Workspaces.Create(ctx, organization, options)
+    Tfe->>TFC: POST /organizations/{org}/workspaces
+    TFC-->>Tfe: workspace JSON
+    Tfe-->>Ctrl: *tfe.Workspace
+    Ctrl-->>User: print workspace as JSON
+```
+
 ## Design decisions
 
 - **Thin wrapper over `go-tfe`.** TECLI does not reimplement Terraform Cloud logic. Each command maps to one `go-tfe` call, so the output mirrors the API response. Upgrading `go-tfe` is the main way new API behavior reaches the CLI.

README.md

@@ -174,7 +174,21 @@ The `configure` command reads and writes the credentials file only. It does not
 
 ## Architecture
 
-TECLI is a thin command-line wrapper around `hashicorp/go-tfe`. The `main` package calls `cmd.Execute()`, which builds a Cobra command tree. Each command validates flags, marshals them into `go-tfe` option structs, calls the Terraform Cloud API, and prints the JSON response. For components, data flow, and design decisions, see [ARCHITECTURE.md](ARCHITECTURE.md).
+TECLI is a thin command-line wrapper around `hashicorp/go-tfe`. The `main` package calls `cmd.Execute()`, which builds a Cobra command tree. Each command validates flags, marshals them into `go-tfe` option structs, calls the Terraform Cloud API, and prints the JSON response.
+
+```mermaid
+%% High-level request flow
+flowchart LR
+    user([You / CI pipeline]) --> cli["tecli<br/>Cobra command"]
+    cli --> resolve["Resolve org and token<br/>TFC_* env vars, then profile"]
+    config[("credentials.yaml<br/>+ TFC_* env vars")] --> resolve
+    resolve --> gotfe["hashicorp/go-tfe<br/>client"]
+    gotfe --> tfc[("Terraform Cloud /<br/>Enterprise API")]
+    tfc --> gotfe
+    gotfe --> out["JSON response<br/>printed to stdout"]
+```
+
+For components, data flow, and design decisions, see [ARCHITECTURE.md](ARCHITECTURE.md).
 
 ## Troubleshooting