feat: In-repo Documentation (#246)

* docs: add documentation

* docs: Improvements

* docs: Improvements

* chore: Diagram fix

* docs: File name improvements

* docs: Improvements

* docs: Improvements

* chore: Improvements

* chore: Improvements

* chore: Improvements

* chore: Update skills to ensure docs are up to date

Author: zeljkoX

.agents/skills/deploy-guardian-aws/SKILL.md

@@ -8,6 +8,9 @@ description: Deploy, update, inspect, and troubleshoot the repository AWS ECS en
 Read the current source of truth at the start of every task:
 
 - `docs/SERVER_AWS_DEPLOY.md`
+- `docs/PRODUCTION.md`
+- `docs/architecture/infra.md`
+- `docs/runbooks/secrets.md`
 - `scripts/aws-deploy.sh`
 - `infra/variables.tf`
 - `infra/terraform.tfvars.example`
@@ -19,6 +22,8 @@ Trust these sources in this order:
 2. `infra/*.tf` and `infra/variables.tf` for actual Terraform behavior
 3. `docs/SERVER_AWS_DEPLOY.md` and `infra/README.md` for operator workflow
 
+When deployment commands, Terraform variables, secret names, DNS behavior, runtime defaults, or supported stack topology change, update the matching operator docs in the same task. Use the Documentation Impact Check in `AGENTS.md` to avoid stale deploy guidance.
+
 ## Preflight
 
 1. Verify AWS identity, Docker, and Terraform:
@@ -167,3 +172,4 @@ Report:
 - Terraform outputs that changed
 - health checks performed
 - blockers found between state, docs, and Terraform code
+- docs checked or updated

.agents/skills/guardian-change-impact/SKILL.md

@@ -43,7 +43,9 @@ Prefer current source files over prose docs when they disagree.
    If a lower layer changes, name every upstream layer that must be inspected or updated in the same task.
 4. Choose the smallest sufficient validation set.
    Map the impact classification to the minimum cargo, npm, and manual smoke coverage. Use `guardian-validation-matrix` if the change is already understood and only the verification set needs to be chosen.
-5. Hand off to a narrower skill when appropriate.
+5. Identify documentation impact.
+   Use the Documentation Impact Check in `AGENTS.md` to name the exact docs, specs, SDK references, or example quickstarts that must be checked or updated.
+6. Hand off to a narrower skill when appropriate.
    - Use `guardian-contract-change` for endpoint, payload, or enum changes.
    - Use `guardian-multisig-proposal-lifecycle` for proposal or offline flow changes.
    - Use `guardian-auth-signature-flows` for auth, keystore, Falcon, ECDSA, or ack changes.

.agents/skills/guardian-contract-change/SKILL.md

@@ -51,6 +51,7 @@ If the change touches proposal payloads or account state shapes, also inspect bo
    Proposal metadata, state objects, ack fields, and status transitions are the common triggers.
 6. Update examples and docs when the change is visible to users or integrators.
    Start with `examples/demo`, `examples/smoke-web`, and `examples/web`.
+   Use the Documentation Impact Check in `AGENTS.md` to pick the matching `spec/`, `docs/`, SDK, and example docs.
 7. Run the smallest meaningful validation set, then expand if high-risk.
 
 ## Guardrails
@@ -70,5 +71,6 @@ Report:
 - transport surfaces affected
 - client parity work completed
 - upstream SDK or example fallout
+- docs checked or updated
 - tests and smoke checks run
 - any intentionally skipped propagation with reason

.agents/skills/guardian-multisig-proposal-lifecycle/SKILL.md

@@ -43,7 +43,9 @@ Read the current workflow surface before editing:
 4. Update the nearest example surface.
    - `examples/demo` for Rust flow verification
    - `examples/smoke-web` and `examples/web` for browser flow verification
-5. Validate the minimal affected path first, then expand to adjacent risky paths.
+5. Check documentation impact when lifecycle behavior, public SDK methods, proposal metadata, offline/import/export format, or example startup changes.
+   Start with `docs/MULTISIG_SDK.md`, affected example docs, and the Documentation Impact Check in `AGENTS.md`.
+6. Validate the minimal affected path first, then expand to adjacent risky paths.
 
 ## Guardrails
 
@@ -80,6 +82,7 @@ Report:
 - Rust files updated
 - TypeScript files updated
 - example surfaces updated or checked
+- docs checked or updated
 - lifecycle invariants preserved
 - targeted tests and smoke coverage
 - gaps or skipped paths

.agents/skills/guardian-validation-matrix/SKILL.md

@@ -36,7 +36,9 @@ Read:
    - the change affects proposal lifecycle or canonicalization
    - the change affects browser signers or user-visible examples
 4. Add manual smoke when a lower-layer change is observable in `examples/demo` or `examples/smoke-web`.
-5. Prefer existing specialized skills over duplicating their workflow.
+5. Include a documentation check when the change affects user-visible behavior, configuration, public APIs, SDK methods, auth/signature behavior, deployment, smoke-test workflow, or example startup.
+   Use the Documentation Impact Check in `AGENTS.md` for the target files.
+6. Prefer existing specialized skills over duplicating their workflow.
 
 ## Guardrails
 
@@ -61,6 +63,7 @@ Produce:
 
 - exact ordered commands to run
 - manual smoke required
+- docs to check or update
 - why each command is included
 - what was intentionally skipped
 - next expansion step if the first layer of checks fails

.agents/skills/smoke-test-evm-proposal-support/SKILL.md

@@ -15,6 +15,7 @@ Read current source before assuming labels, endpoints, or response shapes:
 - `examples/evm-smoke-web/src/App.tsx`
 - `crates/server/src/api/evm.rs`
 - `crates/server/src/evm/`
+- `speckit/features/001-evm-proposal-support/`
 
 Run the focused checks before manual browser work:
 
@@ -27,6 +28,8 @@ cd examples/evm-smoke-web && npm run typecheck && npm run build
 
 Use `git diff -- packages/guardian-client crates/client crates/shared` when the user wants the EVM client isolated from the base clients. Those paths should stay unchanged unless a separate contract change requires them.
 
+When EVM endpoints, proposal shapes, chain configuration, session auth, finality behavior, smoke setup, or browser fields change, update the EVM quickstart/spec, `packages/guardian-evm-client` docs, and `examples/evm-smoke-web` guidance as applicable.
+
 ## Local Stack
 
 Start or verify Anvil:
@@ -184,5 +187,6 @@ Report:
 - number of signatures collected and the signer IDs
 - executable payload/signature result
 - browser and wallet used when running the Vite app
+- docs checked or updated
 - every setup or smoke error observed, including recovered errors
 - checks skipped with reason

.agents/skills/smoke-test-operator-dashboard/SKILL.md

@@ -23,6 +23,8 @@ Use `examples/operator-smoke-web` as the primary smoke surface for operator auth
    - `packages/guardian-operator-client/src/http.ts`
    - `crates/server/src/api/dashboard.rs`
    - `crates/server/src/dashboard/mod.rs`
+   - `docs/DASHBOARD.md`
+   - `docs/PRODUCTION.md`
 2. Run the focused checks:
    ```bash
    cd packages/guardian-operator-client && npm run typecheck && npm test && npm run build
@@ -119,6 +121,10 @@ Use `GUARDIAN_URL=http://127.0.0.1:3000` for local runs. For deployed runs, use
 - Empty account list is not a failure by itself; fetch detail only when the list returns an account ID.
 - A server restart clears in-memory sessions; log in again after restart.
 
+## Documentation Impact
+
+When operator auth, permission vocabulary, account API shapes, session/cookie behavior, local smoke setup, or deployed target assumptions change, update the matching dashboard, production, operator-client, and `examples/operator-smoke-web` docs. Use the Documentation Impact Check in `AGENTS.md` for the target files.
+
 ## Report
 
 Report:
@@ -131,5 +137,6 @@ Report:
 - account list count
 - account detail result, or skipped because the list was empty
 - logout result
+- docs checked or updated
 - every error observed, including recovered errors
 - checks that passed and checks skipped with reason

.env.example

@@ -2,9 +2,9 @@
 GUARDIAN_ENV=dev
 
 # Filesystem Storage
-GUARDIAN_STORAGE_PATH=/var/guardian/storage
-GUARDIAN_METADATA_PATH=/var/guardian/metadata
-GUARDIAN_KEYSTORE_PATH=/var/guardian/keystore
+GUARDIAN_STORAGE_PATH=.guardian/storage
+GUARDIAN_METADATA_PATH=.guardian/metadata
+GUARDIAN_KEYSTORE_PATH=.guardian/keystore
 
 # Optional Postgres Storage
 # Inside docker compose: host is "postgres" (the service name in docker-compose.postgres.yml)

.gitignore

@@ -4,6 +4,7 @@ store.sqlite3
 /var/
 miden-client.toml
 templates/
+.guardian/
 .env
 .env.evm
 .env.prod

AGENTS.md

@@ -7,25 +7,36 @@ It is optimized for safe, cross-layer changes in a multi-language codebase.
 
 Work from the bottom up:
 
-1. `crates/server` (core system of record)
-2. `crates/client` and `packages/guardian-client` (base Rust/TS clients over GUARDIAN)
-3. `crates/miden-multisig-client` and `packages/miden-multisig-client` (higher-level multisig SDKs)
+1. `crates/server` (core system of record — gRPC, HTTP REST, operator dashboard, optional EVM)
+2. Base clients (one per server surface)
+   - `crates/client` + `packages/guardian-client` (Rust gRPC + TS HTTP REST for the per-account API)
+   - `packages/guardian-operator-client` (TS HTTP client for the operator dashboard surface)
+   - `packages/guardian-evm-client` (TS HTTP client for the feature-gated EVM surface)
+3. Higher-level SDKs
+   - `crates/miden-multisig-client` + `packages/miden-multisig-client` (multisig flow on top of base clients)
 4. `examples/` (verification and debugging surfaces)
-   - `examples/demo` = CLI/TUI multisig flow
-   - `examples/web` = browser multisig flow
+   - `examples/demo` = CLI/TUI multisig flow (Rust)
+   - `examples/web` = browser multisig flow (TS)
    - `examples/rust` = low-level Rust integration examples
+   - `examples/smoke-web` = TS multisig smoke harness
+   - `examples/operator-smoke-web` = operator dashboard auth + account-API smoke harness
+   - `examples/evm-smoke-web` = EVM proposal lifecycle smoke harness
 
-If a behavior changes in a lower layer, verify and propagate impact upward.
+If a behavior changes in a lower layer, verify and propagate impact upward across every relevant base client.
 
 ## 2) Repo Map
 
-- `crates/server`: GUARDIAN server (HTTP + gRPC), storage, metadata, auth, canonicalization jobs
-- `crates/client`: Rust gRPC client SDK
-- `packages/guardian-client`: TS HTTP client SDK
+- `crates/server`: GUARDIAN server — gRPC + HTTP + `/dashboard/*` + feature-gated `/evm/*`, storage, metadata, auth, canonicalization jobs
+- `crates/client`: Rust gRPC client SDK (per-account API)
+- `packages/guardian-client`: TS HTTP REST client SDK (per-account API)
+- `packages/guardian-operator-client`: TS HTTP client for the operator dashboard surface (`/dashboard/*`); session-cookie auth, permission vocabulary
+- `packages/guardian-evm-client`: TS HTTP client for the feature-gated EVM surface (`/evm/*`)
 - `crates/miden-multisig-client`: Rust multisig SDK on top of Miden + GUARDIAN
 - `packages/miden-multisig-client`: TS multisig SDK on top of Miden + GUARDIAN
 - `crates/shared`: shared Rust primitives/utilities
 - `spec/`: system and protocol-level behavior docs
+- `docs/`: contributor- and operator-facing documentation hub (start at `docs/CONCEPTS.md`)
+- `infra/`: Terraform for the AWS reference deployment
 - `examples/`: validation apps and reference flows
 
 ## 3) Core Change Rules
@@ -46,15 +57,19 @@ Use this when changing endpoints, payloads, status enums, signatures, or auth be
    - HTTP shapes/serialization in server services and API modules
 2. Update Rust client compatibility:
    - `crates/client` (proto, request/response mapping, auth/signature handling)
-3. Update TS client compatibility:
-   - `packages/guardian-client/src/server-types.ts`
-   - request/response adapters and tests
+3. Update TS client compatibility (each affected surface):
+   - `packages/guardian-client/src/server-types.ts` — per-account API
+   - `packages/guardian-operator-client` — when `/dashboard/*` shapes, permission vocabulary, or session/cookie semantics change
+   - `packages/guardian-evm-client` — when `/evm/*` shapes change
+   - request/response adapters and tests in each touched package
 4. Update multisig SDK layers if proposal/state shape changed:
    - `crates/miden-multisig-client`
    - `packages/miden-multisig-client`
-5. Validate via examples:
-   - `examples/demo` for CLI flow
-   - `examples/web` for browser flow
+5. Validate via examples (use the matching smoke harness for the surface you changed):
+   - `examples/demo` for the Rust CLI multisig flow
+   - `examples/web` / `examples/smoke-web` for the TS multisig flow
+   - `examples/operator-smoke-web` for dashboard / operator-client changes
+   - `examples/evm-smoke-web` for EVM proposal flow changes
 6. Run targeted tests, then broader suite.
 
 ## 5) Layer-Specific Guidance
@@ -79,6 +94,20 @@ Use this when changing endpoints, payloads, status enums, signatures, or auth be
 - Keep `server-types.ts` aligned with real server JSON responses.
 - Keep conversion code explicit rather than permissive.
 - Validate error-shape handling (`GuardianHttpError`) when endpoint responses change.
+- This client is HTTP REST against `:3000`; it does **not** speak gRPC. Do not assume parity with `crates/client` at the transport layer.
+
+### TS Operator Client (`packages/guardian-operator-client`)
+
+- Targets the `/dashboard/*` surface, **not** the per-account API. It is a separate auth domain: challenge → Falcon-signed session → cookie, not per-request `x-pubkey`/`x-signature` headers.
+- When the server's permission vocabulary (`dashboard:read`, `accounts:pause`, `policies:write`) or allowlist payload shape changes, update `permissions.ts` and the allowlist parsing tests in the same PR.
+- Validate cookie / session expectations when changing `/dashboard/auth/*` shapes; the operator allowlist is hot-reloaded on every challenge and authenticated request, so don't add restart-required assumptions.
+- The matching smoke harness is `examples/operator-smoke-web`.
+
+### TS EVM Client (`packages/guardian-evm-client`)
+
+- Feature-gated against the server's `evm` build feature. Treat the client as optional in cross-layer changes — only touch it when server `/evm/*` shapes move.
+- The allowed chain set is derived from `GUARDIAN_EVM_RPC_URLS` keys on the server side; the client should not maintain its own allowlist.
+- Validate against `examples/evm-smoke-web` when changing proposal shapes, session auth, or finality logic.
 
 ### Rust Multisig SDK (`crates/miden-multisig-client`)
 
@@ -121,6 +150,8 @@ cargo test -p guardian-server --features e2e
 
 ```bash
 cd packages/guardian-client && npm test
+cd packages/guardian-operator-client && npm test
+cd packages/guardian-evm-client && npm test
 cd packages/miden-multisig-client && npm test
 ```
 
@@ -150,31 +181,48 @@ When touching any high-risk area, add or update tests before finishing.
 Before finishing, confirm all are true:
 
 1. Architecture impact assessed bottom-up (server -> clients -> multisig -> examples).
-2. Protocol/data-shape changes reflected in both Rust and TS stacks.
-   - If server contract changed, updates in `crates/client` and `packages/guardian-client` must be included in the same PR.
+2. Protocol/data-shape changes reflected in every affected client surface.
+   - Per-account API change → `crates/client` **and** `packages/guardian-client` in the same PR.
+   - Dashboard `/dashboard/*` change → `packages/guardian-operator-client` in the same PR.
+   - EVM `/evm/*` change → `packages/guardian-evm-client` in the same PR.
 3. Tests updated where behavior changed.
 4. At least one upstream consumer validated for changed lower-layer behavior.
 5. README/docs touched if external behavior changed.
 6. No unrelated file churn.
 
-## 9) Practical Defaults
+## 9) Documentation Impact Check
+
+Do not update docs mechanically for every code edit. Do check and update the matching docs whenever a change affects user-visible behavior, public APIs, SDK methods, auth/signature behavior, configuration, deployment flow, smoke-test workflow, or example startup assumptions.
+
+Common mappings:
+
+- Server or API behavior -> `spec/`, `docs/CONCEPTS.md`, SDK docs
+- Multisig SDK behavior -> `docs/MULTISIG_SDK.md`, `examples/demo`, `examples/web`, `examples/smoke-web`
+- Operator/dashboard behavior -> `docs/DASHBOARD.md`, `docs/PRODUCTION.md`, `examples/operator-smoke-web`
+- EVM proposal behavior -> `speckit/features/001-evm-proposal-support/`, `packages/guardian-evm-client`, `examples/evm-smoke-web`
+- Deployment, config, infrastructure, or secrets -> `docs/PRODUCTION.md`, `docs/architecture/infra.md`, `docs/runbooks/secrets.md`, `docs/SERVER_AWS_DEPLOY.md`, `infra/README.md`
+- Local dev or test startup -> `README.md`, `CONTRIBUTING.md`, relevant example README or quickstart
+
+When docs are not updated after a visible behavior change, note why in the final report or PR notes.
+
+## 10) Practical Defaults
 
 - Prefer `rg`/`rg --files` for discovery.
 - Keep edits ASCII unless existing file requires otherwise.
 - Keep comments minimal and only where logic is non-obvious.
 - Avoid speculative refactors during bugfixes.
 
-## 10) Versioning Policy
+## 11) Versioning Policy
 
 - Keep crate/package versions aligned with the active Miden dependency line.
-- Current baseline is Miden `0.13.x`; changes must remain compatible with that line unless migration is explicit.
-- If a change requires moving to a new Miden line (for example `0.14.x`), treat it as a coordinated release task:
+- Current baseline is Miden `0.14.x`; changes must remain compatible with that line unless migration is explicit.
+- If a change requires moving to a new Miden line, treat it as a coordinated release task:
   1. Update workspace/dependency constraints.
   2. Update both multisig SDKs and both base clients as needed.
   3. Re-run cross-layer validation (including examples).
   4. Update docs and changelog/release notes to call out the dependency line change.
 
-## 11) Coding Style (Multisig Focus)
+## 12) Coding Style (Multisig Focus)
 
 Apply these rules especially to:
 - `crates/miden-multisig-client`