From a79407122af8903c93b2b08523b25bb93573b34a Mon Sep 17 00:00:00 2001
From: samzong <samzong.lu@gmail.com>
Date: Thu, 6 Aug 2026 09:52:34 -0400
Subject: [PATCH] docs: add live architecture map and update policy
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Considered and deferred

- AGENTS.md:Multi-Language Parity [BOT-SCOPE]: Pre-existing section still says TypeScript/Go/Rust only while docs/architecture.mmd and scripts/sync-hosts.mjs include python; out of this map-policy change scope.
- docs/architecture.mmd:6 [BOT-TASTE]: Workflow node labels Go-style RunBundledSkillInstall only; TS/Python use camel/snake variants — acceptable for ownership map, not API catalog.

Signed-off-by: samzong <samzong.lu@gmail.com>
---
 AGENTS.md             | 18 +++++++++++++++
 docs/architecture.mmd | 51 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 69 insertions(+)
 create mode 100644 docs/architecture.mmd

diff --git a/AGENTS.md b/AGENTS.md
index e265391..b9ae299 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -134,3 +134,21 @@ Keep diffs small and behavior-led.
 - Do not update docs to describe behavior that is not implemented or covered by fixtures.
 - Do not widen v0.1 scope to make an isolated task feel complete.
 - If a requested change weakens conflict safety, metadata ownership, or parity, stop and surface the trade-off first.
+
+## Live Architecture Map
+
+The canonical architecture diagram is `docs/architecture.mmd`.
+
+Update it when these ownership boundaries change:
+
+- bundle resolution, validation, host resolution, installer semantics, or workflow entry points;
+- `.kitup.json` metadata ownership or shared schema ownership (`spec/hosts.schema.json` and `testdata/cases.schema.json`);
+- GitHub API integration or the data it returns;
+- shared golden-case parity enforcement or host-spec generation (`scripts/sync-hosts.mjs`);
+- the set of SDK language implementations.
+
+Do not update the diagram for internal refactors that preserve the same owner seams,
+tests, formatting, copy, content, or dependency-only changes.
+
+The map is the canonical source for documented system boundaries only.
+Code and runtime remain authoritative for behavior, schemas, and supported values.
diff --git a/docs/architecture.mmd b/docs/architecture.mmd
new file mode 100644
index 0000000..13bc913
--- /dev/null
+++ b/docs/architecture.mmd
@@ -0,0 +1,51 @@
+flowchart TB
+    AUTHOR["CLI Author\n(embedding CLI)"]:::actor
+
+    subgraph SDK["SDK (ts / go / rust / python)"]
+        direction TB
+        WORKFLOW["Install Workflow\nRunBundledSkillInstall"]:::execution
+        BUNDLE["Bundle Resolver\nlocal · embedded · GitHub"]:::execution
+        VALIDATE["Validator\nSKILL.md frontmatter"]:::execution
+        HOST["Host Resolver\nids · aliases · detection · targets"]:::execution
+        INSTALL["Installer\nplan · conflict policy · copy · update · uninstall"]:::execution
+        REPORT["Reports\nInstallReport · UninstallReport"]:::execution
+    end
+
+    HOSTSPEC["Host Spec\nspec/hosts.json"]:::contract
+    SCHEMAS["Schemas\nspec/hosts.schema.json\ntestdata/cases.schema.json"]:::contract
+    CASES["Golden Cases\ntestdata/cases/*.json"]:::contract
+    GENHOSTS["Generated Host Constants\nts / go / rust / python"]:::artifact
+    VERIFY["Verification\ncheck.mjs · sync-hosts.mjs"]:::control
+    GITHUB["GitHub API"]:::external
+    TARGETS["Agent Host\nDirectory State"]:::state
+    METADATA[".kitup.json"]:::state
+
+    AUTHOR -->|"provides flags"| WORKFLOW
+    WORKFLOW --> BUNDLE
+    WORKFLOW --> HOST
+    BUNDLE --> VALIDATE
+    BUNDLE -->|"fetches trees, blobs"| GITHUB
+    GENHOSTS -.->|"provides host data"| HOST
+    TARGETS -->|"path existence"| HOST
+    VALIDATE --> INSTALL
+    HOST --> INSTALL
+    INSTALL -->|"copies, updates, removes"| TARGETS
+    INSTALL -->|"writes .kitup.json"| METADATA
+    INSTALL -->|"returns report"| REPORT
+
+    SCHEMAS -.-> HOSTSPEC
+    SCHEMAS -.-> CASES
+    HOSTSPEC -.->|"generates"| GENHOSTS
+    VERIFY -.-> HOSTSPEC
+    VERIFY -.->|"checks parity"| CASES
+    VERIFY -.-> GENHOSTS
+
+    classDef actor fill:#1f2937,stroke:#94a3b8,color:#f8fafc,stroke-width:1px;
+    classDef control fill:#241b3a,stroke:#a78bfa,color:#ede9fe,stroke-width:1px;
+    classDef execution fill:#0b3b4a,stroke:#22d3ee,color:#e0f2fe,stroke-width:1px;
+    classDef contract fill:#3b2f0b,stroke:#fbbf24,color:#fef3c7,stroke-width:1px;
+    classDef artifact fill:#2d1f4e,stroke:#c084fc,color:#f3e8ff,stroke-width:1px;
+    classDef state fill:#14532d,stroke:#4ade80,color:#dcfce7,stroke-width:1px;
+    classDef external fill:#2f1d12,stroke:#fb923c,color:#ffedd5,stroke-width:1px;
+
+    style SDK fill:#071c26,stroke:#22d3ee,color:#e0f2fe