@robotaccomplice/architext 1.0.0

package/docs/architext/LLM_ARCHITEXT.md

@@ -0,0 +1,64 @@
+# LLM Architext Contract
+
+Architext JSON files are the machine-readable architecture source of truth for
+this project.
+
+When architecture changes, update the relevant files under
+`docs/architext/data/` before claiming the implementation is complete.
+
+## Required Behavior
+
+- Read existing Architext data before editing it.
+- Reuse existing IDs for existing concepts.
+- Create new nodes before referencing them from flows or views.
+- Keep flows ordered.
+- Update data classification whenever data movement changes.
+- Update risks when adding external dependencies, persistence, async
+  processing, sensitive data handling, trust boundary crossings, or operational
+  complexity.
+- Prefer source-path-backed claims.
+- Mark uncertainty explicitly instead of inventing details.
+- Run `architext validate [path]` after changing data.
+- Do not claim Architext is current if validation failed or was skipped.
+- Do not edit copied viewer, schema, package, Vite, or local tool files in a
+  target repository. Those files are package-owned in Architext 1.0+.
+
+## Persistence Rules
+
+Persist these project-owned files in git:
+
+- `docs/architext/data/*.json`
+- `docs/architext/.architext.json`
+- repository-level `AGENTS.md` or `CLAUDE.md` Architext instructions, when
+  present
+
+Do not persist generated or local runtime artifacts:
+
+- `docs/architext/dist/`
+- `.DS_Store`
+- editor/OS temp files
+- local server logs
+- screenshots created only for debugging unless intentionally added to project
+  documentation
+
+If the target project does not already ignore generated artifacts, use
+`architext sync [path]` to update lifecycle metadata, instructions, and ignore
+rules.
+
+## Update Triggers
+
+Update Architext when changing:
+
+- module or service responsibilities
+- public or internal APIs
+- queues, topics, jobs, or workers
+- data stores
+- external integrations
+- authentication or authorization behavior
+- trust boundaries
+- deployment topology
+- observability paths
+- sensitive data handling
+- core business flows
+- architecture decisions
+- known architecture risks

package/docs/architext/README.md

@@ -0,0 +1,120 @@
+# Architext Template
+
+This directory is the package-owned Architext viewer, schema, and starter data.
+Target repositories should not copy or edit this implementation. They own only
+their `docs/architext/data/*.json` files, lifecycle metadata, and optional
+repository-level agent instructions.
+
+## Commands
+
+From a target project root, use the global Architext CLI:
+
+```sh
+architext serve
+architext validate
+architext build
+architext doctor
+architext prompt
+```
+
+Each command also accepts an optional target path:
+
+```sh
+architext serve /path/to/project
+architext validate /path/to/project
+```
+
+If you are developing Architext itself, use the local npm scripts:
+
+Install local dependencies:
+
+```sh
+npm install
+```
+
+Validate architecture data:
+
+```sh
+npm run validate
+```
+
+Run the local development server:
+
+```sh
+npm run dev
+```
+
+Build static assets:
+
+```sh
+npm run build
+```
+
+Preview the static build locally:
+
+```sh
+npm run preview
+```
+
+The npm scripts avoid shell-specific command chains so they work on Windows,
+Linux, and macOS.
+
+## Upgrades
+
+Target repositories are data-only in Architext 1.0+. From the target project
+root, use the package CLI:
+
+```sh
+architext sync
+```
+
+The script detects whether Architext data is absent, current, or from an older
+copied-template install. It prompts before writing files and can create a git
+branch before making changes. Migration preserves `docs/architext/data/*.json`
+by default, removes copied implementation files, updates lifecycle metadata,
+and corrects Architext sections in `AGENTS.md` and `CLAUDE.md`.
+
+The script can also maintain the target repository `.gitignore`. Generated
+local artifacts, especially `docs/architext/dist/`, should be ignored.
+
+The CLI writes lifecycle metadata to `.architext.json`. Keep that file with the
+project so automation can report CLI version, update time, managed instruction
+files, copied-install migration state, and last validation state.
+
+## Management
+
+Useful project-root commands:
+
+```sh
+architext doctor
+architext status --json
+architext prompt --mode architecture-change
+architext clean
+architext clean --node-modules
+architext explain nodes
+```
+
+`doctor` is read-only and should be the first command when an install looks
+stale or broken.
+
+## Data Entry Point
+
+The viewer loads:
+
+```text
+data/manifest.json
+```
+
+The manifest points to the remaining JSON files. Keep paths local to this
+directory. Do not load runtime assets, schemas, scripts, styles, or fonts from
+remote URLs.
+
+## Validation
+
+`npm run validate` performs two checks:
+
+- JSON Schema validation for each data file
+- cross-reference validation for IDs shared across nodes, flows, views, risks,
+  decisions, and data classifications
+
+If validation fails, the architecture model is not trustworthy.

package/docs/architext/data/data-classification.json

@@ -0,0 +1,34 @@
+{
+  "classes": [
+    {
+      "id": "architecture-model",
+      "name": "Architecture model",
+      "sensitivity": "medium",
+      "handling": "Review JSON diffs before trusting generated architecture claims."
+    },
+    {
+      "id": "repository-metadata",
+      "name": "Repository metadata",
+      "sensitivity": "low",
+      "handling": "Lifecycle state may be committed, but it is not the architecture source of truth."
+    },
+    {
+      "id": "agent-instructions",
+      "name": "Agent instructions",
+      "sensitivity": "medium",
+      "handling": "Preserve project-owned instructions and replace only the Architext-managed section."
+    },
+    {
+      "id": "package-assets",
+      "name": "Package assets",
+      "sensitivity": "low",
+      "handling": "Serve locally from the installed package; do not copy into target repositories."
+    },
+    {
+      "id": "validation-output",
+      "name": "Validation output",
+      "sensitivity": "low",
+      "handling": "Use to repair JSON references and schema mismatches before claiming documentation is current."
+    }
+  ]
+}

package/docs/architext/data/decisions.json

@@ -0,0 +1,54 @@
+{
+  "decisions": [
+    {
+      "id": "global-cli-data-only",
+      "status": "accepted",
+      "title": "Use a global CLI with data-only target repositories",
+      "context": "Copied templates made every target repository carry viewer code, schemas, local tools, package files, and dependencies.",
+      "decision": "Architext 1.0 serves viewer assets, schemas, validation, and starter templates from the installed package. Target repositories commit only data, metadata, and optional instructions.",
+      "consequences": ["Per-repository upgrades become smaller", "Global CLI availability becomes the primary operating assumption", "Old copied installs require migration"],
+      "relatedNodes": ["architext-cli", "viewer-runtime", "target-repository", "target-data-files"],
+      "relatedFlows": ["fresh-install", "copied-install-migration", "local-review"]
+    },
+    {
+      "id": "safe-migration",
+      "status": "accepted",
+      "title": "Preserve architecture facts during migration",
+      "context": "Old installs may contain valuable project-owned data mixed with copied package-owned implementation files.",
+      "decision": "Migration preserves docs/architext/data/*.json, removes copied package-owned files, updates metadata, and corrects managed agent instruction sections.",
+      "consequences": ["Architecture facts are not rewritten silently", "Dry-run output must show destructive removals", "Instruction updates are part of migration correctness"],
+      "relatedNodes": ["architext-cli", "target-repository", "target-data-files"],
+      "relatedFlows": ["copied-install-migration"]
+    },
+    {
+      "id": "managed-agent-section",
+      "status": "accepted",
+      "title": "Manage one Architext instruction section",
+      "context": "Agents need current rules, but project-specific instructions outside Architext must remain authoritative.",
+      "decision": "The CLI replaces or appends a single section headed 'Architext Architecture Documentation' in AGENTS.md and CLAUDE.md.",
+      "consequences": ["Old copied-template instructions can be corrected automatically", "Unrelated project instructions are preserved", "Highly unusual Markdown layouts may need manual review"],
+      "relatedNodes": ["architext-cli", "llm-agent", "target-repository"],
+      "relatedFlows": ["copied-install-migration", "architecture-maintenance"]
+    },
+    {
+      "id": "package-owned-schemas",
+      "status": "accepted",
+      "title": "Validate with package-owned schemas",
+      "context": "Committing schemas into every target repository made schema upgrades a repo-by-repo file-copy problem.",
+      "decision": "Schemas ship with the Architext package and are used by architext validate [path].",
+      "consequences": ["Validation behavior tracks the installed CLI version", "Schema migrations must be explicit when data shape changes", "Target repos no longer review schema diffs unless Architext itself changes"],
+      "relatedNodes": ["schema-validator", "package-schemas", "target-data-files"],
+      "relatedFlows": ["architecture-maintenance", "copied-install-migration"]
+    },
+    {
+      "id": "major-version-release",
+      "status": "accepted",
+      "title": "Ship the distribution change as a major version",
+      "context": "The target repository footprint and upgrade behavior are incompatible with the pre-1.0 copied-template model.",
+      "decision": "Release the global CLI/data-only model as Architext 1.0.0.",
+      "consequences": ["Users receive a clear breaking-change boundary", "Existing copied installs are migration inputs", "Documentation can stop describing copied templates as the normal path"],
+      "relatedNodes": ["package-artifacts", "architext-cli"],
+      "relatedFlows": ["release-packaging", "copied-install-migration"]
+    }
+  ]
+}

package/docs/architext/data/flows.json

@@ -0,0 +1,114 @@
+{
+  "flows": [
+    {
+      "id": "fresh-install",
+      "name": "Fresh data-only install",
+      "status": "implemented",
+      "summary": "A maintainer installs Architext into a repository without copying viewer implementation files.",
+      "trigger": "Maintainer runs architext sync [path] in a repository with no Architext data.",
+      "actors": ["maintainer"],
+      "steps": [
+        { "id": "resolve-target", "from": "maintainer", "to": "architext-cli", "action": "resolveTargetPath", "summary": "CLI resolves the optional path argument or defaults to the current directory.", "data": ["repository-metadata"] },
+        { "id": "write-starter-data", "from": "architext-cli", "to": "target-data-files", "action": "writeStarterData", "summary": "CLI writes neutral starter data under docs/architext/data.", "data": ["architecture-model"] },
+        { "id": "write-metadata", "from": "architext-cli", "to": "target-repository", "action": "writeLifecycleMetadata", "summary": "CLI writes docs/architext/.architext.json with install state.", "data": ["repository-metadata"] },
+        { "id": "validate-install", "from": "architext-cli", "to": "schema-validator", "action": "validateStarterModel", "summary": "Package-owned schemas validate the starter model.", "data": ["architecture-model", "validation-output"] }
+      ],
+      "guarantees": ["Target repo does not receive copied viewer, schema, tool, package, or Vite files."],
+      "failureBehavior": ["Invalid starter data fails sync before claiming installation health."],
+      "observability": ["CLI output", "doctor status", "validation output"],
+      "verification": ["architext sync /tmp/repo --yes", "architext validate /tmp/repo"],
+      "knownGaps": ["Install prompt UX still needs real user testing on Windows shells."]
+    },
+    {
+      "id": "copied-install-migration",
+      "name": "Copied install migration",
+      "status": "implemented",
+      "summary": "An existing copied-template install is converted into the 1.0 data-only layout.",
+      "trigger": "Maintainer runs architext sync [path] where docs/architext contains copied implementation files.",
+      "actors": ["maintainer"],
+      "steps": [
+        { "id": "detect-copied-files", "from": "architext-cli", "to": "target-repository", "action": "detectCopiedInstall", "summary": "CLI detects package-owned files such as src, schema, tools, package.json, and Vite config.", "data": ["repository-metadata"] },
+        { "id": "preserve-data", "from": "architext-cli", "to": "target-data-files", "action": "preserveArchitectureData", "summary": "CLI leaves docs/architext/data/*.json untouched unless overwrite is explicit.", "data": ["architecture-model"] },
+        { "id": "rewrite-instructions", "from": "architext-cli", "to": "target-repository", "action": "replaceArchitextInstructionSection", "summary": "CLI replaces old Architext agent sections with global-CLI guidance while preserving unrelated instructions.", "data": ["agent-instructions"] },
+        { "id": "remove-copied-files", "from": "architext-cli", "to": "target-repository", "action": "removePackageOwnedFiles", "summary": "CLI removes copied viewer, schema, tool, package, and Vite files from the target repository.", "data": ["package-assets"] },
+        { "id": "validate-migration", "from": "architext-cli", "to": "schema-validator", "action": "validateMigratedData", "summary": "CLI validates preserved target data against package-owned schemas.", "data": ["architecture-model", "validation-output"] }
+      ],
+      "guarantees": ["Architecture facts are not rewritten silently.", "Agent instructions no longer tell agents to edit copied package-owned files."],
+      "failureBehavior": ["Dry-run exposes destructive removals; validation failure points to repair prompt."],
+      "observability": ["Dry-run output", "doctor copied install status", "Git diff"],
+      "verification": ["architext sync ../roboticus --dry-run", "architext doctor ../roboticus"],
+      "knownGaps": ["Instruction replacement is intentionally marker-based and does not parse arbitrary Markdown ASTs."]
+    },
+    {
+      "id": "architecture-maintenance",
+      "name": "Architecture data maintenance",
+      "status": "implemented",
+      "summary": "An LLM agent updates architecture data in response to real repository changes.",
+      "trigger": "A code change alters architecture, persistence, data flow, external integrations, deployment, risks, or decisions.",
+      "actors": ["llm-agent"],
+      "steps": [
+        { "id": "read-instructions", "from": "llm-agent", "to": "target-repository", "action": "readAgentInstructions", "summary": "Agent reads the managed Architext section and any project-specific constraints.", "data": ["agent-instructions"] },
+        { "id": "read-data", "from": "llm-agent", "to": "target-data-files", "action": "readArchitectureModel", "summary": "Agent reads existing JSON before editing.", "data": ["architecture-model"] },
+        { "id": "edit-data", "from": "llm-agent", "to": "target-data-files", "action": "updateArchitectureFacts", "summary": "Agent updates only project-owned data files and preserves stable IDs.", "data": ["architecture-model"] },
+        { "id": "run-validation", "from": "llm-agent", "to": "schema-validator", "action": "runArchitextValidate", "summary": "Agent runs package-owned validation before claiming completion.", "data": ["validation-output"] }
+      ],
+      "guarantees": ["Package-owned viewer/schema/tool files are not edited in target repositories."],
+      "failureBehavior": ["If validation fails, agent repairs JSON or reports the failure loudly."],
+      "observability": ["Validation result in final answer", "JSON diffs"],
+      "verification": ["architext prompt . --mode architecture-change", "architext validate ."],
+      "knownGaps": ["Generated architecture claims still require human review."]
+    },
+    {
+      "id": "local-review",
+      "name": "Local viewer review",
+      "status": "implemented",
+      "summary": "A maintainer serves the package-owned viewer against target repository data.",
+      "trigger": "Maintainer runs architext serve [path].",
+      "actors": ["maintainer"],
+      "steps": [
+        { "id": "start-server", "from": "maintainer", "to": "architext-cli", "action": "startLocalServer", "summary": "CLI starts the package-owned Vite server with target data directory configured.", "data": ["repository-metadata"] },
+        { "id": "serve-assets", "from": "architext-cli", "to": "viewer-runtime", "action": "servePackageViewer", "summary": "Viewer assets are served from the installed package.", "data": ["package-assets"] },
+        { "id": "load-data", "from": "viewer-runtime", "to": "target-data-files", "action": "fetchTargetData", "summary": "Viewer fetches /data/*.json from the selected target repository.", "data": ["architecture-model"] }
+      ],
+      "guarantees": ["Review requires a local server but not target-local npm dependencies."],
+      "failureBehavior": ["Missing data produces viewer load errors and doctor guidance."],
+      "observability": ["Browser view", "Browser console", "CLI server output"],
+      "verification": ["architext serve ."],
+      "knownGaps": ["The viewer remains a local dev server in normal review mode."]
+    },
+    {
+      "id": "static-export",
+      "name": "Static export",
+      "status": "implemented",
+      "summary": "A maintainer builds a static viewer that includes a copy of selected target data.",
+      "trigger": "Maintainer runs architext build [path].",
+      "actors": ["maintainer"],
+      "steps": [
+        { "id": "build-viewer-assets", "from": "architext-cli", "to": "viewer-runtime", "action": "buildStaticViewer", "summary": "CLI builds package-owned viewer assets into target docs/architext/dist.", "data": ["package-assets"] },
+        { "id": "copy-data", "from": "architext-cli", "to": "static-dist", "action": "copyTargetData", "summary": "CLI copies target data into dist/data for static serving.", "data": ["architecture-model"] }
+      ],
+      "guarantees": ["Generated static output can be served without Vite."],
+      "failureBehavior": ["Stale dist output is treated as generated and can be cleaned."],
+      "observability": ["Build output", "dist file list"],
+      "verification": ["architext build ."],
+      "knownGaps": ["Static export can become stale after data edits."]
+    },
+    {
+      "id": "release-packaging",
+      "name": "Release packaging",
+      "status": "implemented",
+      "summary": "Architext ships the global CLI, package-owned viewer, schemas, and starter templates as a major semver release.",
+      "trigger": "Maintainer prepares a release.",
+      "actors": ["maintainer"],
+      "steps": [
+        { "id": "run-build", "from": "maintainer", "to": "package-artifacts", "action": "runBuildAndValidation", "summary": "Maintainer runs validation and production build.", "data": ["package-assets", "validation-output"] },
+        { "id": "inspect-package", "from": "maintainer", "to": "package-artifacts", "action": "runPackageDryRun", "summary": "Maintainer verifies npm package contents exclude target generated artifacts.", "data": ["package-assets"] }
+      ],
+      "guarantees": ["1.0.0 marks the breaking distribution model change."],
+      "failureBehavior": ["Package contents mismatch blocks release."],
+      "observability": ["npm pack --dry-run output", "build output"],
+      "verification": ["npm pack --dry-run"],
+      "knownGaps": ["A CI workflow is still needed to enforce packaging checks automatically."]
+    }
+  ]
+}

package/docs/architext/data/glossary.json

@@ -0,0 +1,24 @@
+{
+  "terms": [
+    {
+      "term": "Data-only install",
+      "definition": "An Architext target repository layout that commits architecture JSON, lifecycle metadata, and optional instructions, but not viewer code or schemas."
+    },
+    {
+      "term": "Copied install",
+      "definition": "A pre-1.0 Architext target repository that contains copied viewer, schema, tool, package, and Vite files under docs/architext."
+    },
+    {
+      "term": "Package-owned runtime",
+      "definition": "The Architext CLI, viewer, schemas, validation tools, and starter templates shipped by the installed npm package."
+    },
+    {
+      "term": "Target-owned data",
+      "definition": "The docs/architext/data/*.json files that describe a project architecture and are reviewed as part of that project."
+    },
+    {
+      "term": "Managed Architext section",
+      "definition": "The repository-level AGENTS.md or CLAUDE.md section headed 'Architext Architecture Documentation' that the CLI can replace during migration."
+    }
+  ]
+}

package/docs/architext/data/manifest.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": "1.0.0",
+  "project": {
+    "id": "architext",
+    "name": "Architext",
+    "summary": "Global CLI and local architecture viewer for data-only repository architecture maps."
+  },
+  "generatedAt": "2026-05-14T00:00:00.000Z",
+  "defaultViewId": "system-map",
+  "files": {
+    "nodes": "nodes.json",
+    "flows": "flows.json",
+    "views": "views.json",
+    "dataClassification": "data-classification.json",
+    "decisions": "decisions.json",
+    "risks": "risks.json",
+    "glossary": "glossary.json"
+  },
+  "notes": [
+    "This self-hosted model describes Architext itself after the 1.0 global CLI migration.",
+    "Target repositories own architecture data only; viewer, schemas, validation, and starter templates are package-owned."
+  ]
+}

package/docs/architext/data/nodes.json

@@ -0,0 +1,194 @@
+{
+  "nodes": [
+    {
+      "id": "maintainer",
+      "type": "actor",
+      "name": "Maintainer",
+      "summary": "Engineer installing, migrating, validating, or reviewing Architext in a repository.",
+      "responsibilities": ["Run lifecycle commands", "Review generated architecture data", "Keep instructions current"],
+      "owner": "Project maintainers",
+      "sourcePaths": [],
+      "runtime": "Terminal workflow",
+      "interfaces": ["architext CLI"],
+      "dependencies": ["architext-cli"],
+      "dataHandled": ["architecture-model", "repository-metadata", "agent-instructions"],
+      "security": ["Reviews generated changes before commit"],
+      "observability": ["CLI output", "Git diff"],
+      "relatedFlows": ["fresh-install", "copied-install-migration", "local-review"],
+      "relatedDecisions": ["global-cli-data-only"],
+      "knownRisks": ["outdated-agent-instructions"],
+      "verification": ["architext doctor ."]
+    },
+    {
+      "id": "llm-agent",
+      "type": "actor",
+      "name": "LLM Agent",
+      "summary": "Automation maintaining architecture JSON while changing a target repository.",
+      "responsibilities": ["Read architecture data before code changes", "Update data JSON when architecture changes", "Run validation"],
+      "owner": "Target repository workflow",
+      "sourcePaths": [],
+      "runtime": "Agent or coding assistant session",
+      "interfaces": ["AGENTS.md", "CLAUDE.md", "docs/architext/data/*.json"],
+      "dependencies": ["target-repository", "architext-cli"],
+      "dataHandled": ["architecture-model", "agent-instructions", "validation-output"],
+      "security": ["Must not edit package-owned viewer/schema/tool files in target repositories"],
+      "observability": ["Validation result in final response"],
+      "relatedFlows": ["architecture-maintenance"],
+      "relatedDecisions": ["managed-agent-section"],
+      "knownRisks": ["outdated-agent-instructions"],
+      "verification": ["architext prompt . --mode architecture-change"]
+    },
+    {
+      "id": "architext-cli",
+      "type": "service",
+      "name": "Architext CLI",
+      "summary": "Global Node CLI that manages installs, migrations, validation, serving, builds, prompts, and diagnostics.",
+      "responsibilities": ["Resolve target paths", "Write starter data", "Migrate copied installs", "Serve package viewer", "Run validation"],
+      "owner": "Architext maintainers",
+      "sourcePaths": ["tools/architext-adopt.mjs"],
+      "runtime": "Node.js 20+ global executable",
+      "interfaces": ["architext <command> [path]", "status --json"],
+      "dependencies": ["viewer-runtime", "schema-validator", "target-repository", "package-artifacts"],
+      "dataHandled": ["architecture-model", "repository-metadata", "agent-instructions", "validation-output"],
+      "security": ["Dry-run exposes destructive migration changes", "Architecture facts are not rewritten silently"],
+      "observability": ["Console output", "doctor/status JSON"],
+      "relatedFlows": ["fresh-install", "copied-install-migration", "local-review", "static-export"],
+      "relatedDecisions": ["global-cli-data-only", "safe-migration"],
+      "knownRisks": ["migration-data-loss", "package-runtime-drift"],
+      "verification": ["node tools/architext-adopt.mjs --help", "node tools/architext-adopt.mjs status . --json"]
+    },
+    {
+      "id": "viewer-runtime",
+      "type": "client",
+      "name": "Package-owned viewer",
+      "summary": "React/Vite viewer served from the installed Architext package rather than copied into target repositories.",
+      "responsibilities": ["Render diagrams", "Fetch target data through local server", "Support work modes and details panels"],
+      "owner": "Architext maintainers",
+      "sourcePaths": ["docs/architext/src/main.tsx", "docs/architext/src/styles.css", "docs/architext/vite.config.ts"],
+      "runtime": "Vite development server or built static assets",
+      "interfaces": ["http://127.0.0.1:4317", "/data/*.json"],
+      "dependencies": ["target-data-files"],
+      "dataHandled": ["architecture-model", "package-assets"],
+      "security": ["Serves local package assets only", "No runtime CDN dependency"],
+      "observability": ["Browser console", "Rendered diagrams"],
+      "relatedFlows": ["local-review", "static-export"],
+      "relatedDecisions": ["global-cli-data-only"],
+      "knownRisks": ["package-runtime-drift"],
+      "verification": ["architext serve .", "architext build ."]
+    },
+    {
+      "id": "schema-validator",
+      "type": "module",
+      "name": "Schema validator",
+      "summary": "AJV-based validator that checks schemas, unique IDs, and cross-file references.",
+      "responsibilities": ["Validate JSON Schema", "Reject unresolved references", "Report duplicate IDs"],
+      "owner": "Architext maintainers",
+      "sourcePaths": ["docs/architext/tools/validate-architext.mjs", "docs/architext/schema/*.schema.json"],
+      "runtime": "Node.js process invoked by CLI",
+      "interfaces": ["architext validate [path]", "--data-dir", "--schema-dir"],
+      "dependencies": ["target-data-files", "package-schemas"],
+      "dataHandled": ["architecture-model", "validation-output"],
+      "security": ["Fails closed on invalid model"],
+      "observability": ["Validation errors by file and reference context"],
+      "relatedFlows": ["fresh-install", "architecture-maintenance", "copied-install-migration"],
+      "relatedDecisions": ["package-owned-schemas"],
+      "knownRisks": ["schema-version-mismatch"],
+      "verification": ["architext validate ."]
+    },
+    {
+      "id": "target-repository",
+      "type": "software-system",
+      "name": "Target repository",
+      "summary": "Any project that adopts Architext and commits only architecture data, metadata, and instructions.",
+      "responsibilities": ["Own architecture facts", "Store lifecycle metadata", "Keep generated build output ignored"],
+      "owner": "Target project maintainers",
+      "sourcePaths": ["docs/architext/data/*.json", "docs/architext/.architext.json", "AGENTS.md", "CLAUDE.md"],
+      "runtime": "Git repository",
+      "interfaces": ["Filesystem", "Git diff", "package.json scripts"],
+      "dependencies": [],
+      "dataHandled": ["architecture-model", "repository-metadata", "agent-instructions"],
+      "security": ["Project instructions must remain authoritative outside the managed Architext section"],
+      "observability": ["Git status", "doctor output"],
+      "relatedFlows": ["fresh-install", "copied-install-migration", "architecture-maintenance"],
+      "relatedDecisions": ["global-cli-data-only"],
+      "knownRisks": ["outdated-agent-instructions", "migration-data-loss"],
+      "verification": ["architext doctor ."]
+    },
+    {
+      "id": "target-data-files",
+      "type": "data-store",
+      "name": "Target data files",
+      "summary": "Project-owned Architext JSON files committed under docs/architext/data.",
+      "responsibilities": ["Store nodes", "Store flows", "Store views", "Store decisions and risks"],
+      "owner": "Target project maintainers",
+      "sourcePaths": ["docs/architext/data/*.json"],
+      "runtime": "Version-controlled JSON",
+      "interfaces": ["manifest.json file map", "JSON Schema"],
+      "dependencies": [],
+      "dataHandled": ["architecture-model"],
+      "security": ["Reviewed as code"],
+      "observability": ["Validation output", "Rendered viewer"],
+      "relatedFlows": ["architecture-maintenance", "local-review", "static-export"],
+      "relatedDecisions": ["global-cli-data-only"],
+      "knownRisks": ["schema-version-mismatch"],
+      "verification": ["architext validate ."]
+    },
+    {
+      "id": "package-schemas",
+      "type": "module",
+      "name": "Package schemas",
+      "summary": "Architext-owned JSON Schemas shipped with the global package.",
+      "responsibilities": ["Define data contract", "Provide validation source of truth"],
+      "owner": "Architext maintainers",
+      "sourcePaths": ["docs/architext/schema/*.schema.json"],
+      "runtime": "Package files",
+      "interfaces": ["JSON Schema 2020-12"],
+      "dependencies": [],
+      "dataHandled": ["package-assets"],
+      "security": ["Schemas are not target-repository-owned"],
+      "observability": ["npm pack --dry-run"],
+      "relatedFlows": ["architecture-maintenance", "copied-install-migration"],
+      "relatedDecisions": ["package-owned-schemas"],
+      "knownRisks": ["schema-version-mismatch"],
+      "verification": ["npm pack --dry-run"]
+    },
+    {
+      "id": "package-artifacts",
+      "type": "deployment-unit",
+      "name": "NPM package artifacts",
+      "summary": "Published files that include CLI code, viewer source/assets, schemas, starter templates, and documentation.",
+      "responsibilities": ["Distribute global CLI", "Bundle local runtime dependencies", "Exclude target generated artifacts"],
+      "owner": "Architext maintainers",
+      "sourcePaths": ["package.json", "package-lock.json", "docs/architext", "tools"],
+      "runtime": "npm package",
+      "interfaces": ["npm install -g @robotaccomplice/architext", "npm pack --dry-run"],
+      "dependencies": ["architext-cli", "viewer-runtime", "package-schemas"],
+      "dataHandled": ["package-assets"],
+      "security": ["Package contents are reviewed before release"],
+      "observability": ["npm pack file list"],
+      "relatedFlows": ["release-packaging"],
+      "relatedDecisions": ["major-version-release"],
+      "knownRisks": ["package-runtime-drift"],
+      "verification": ["npm pack --dry-run"]
+    },
+    {
+      "id": "static-dist",
+      "type": "deployment-unit",
+      "name": "Static viewer export",
+      "summary": "Generated static viewer output for offline or tiny-server review.",
+      "responsibilities": ["Contain built viewer assets", "Include a copy of selected target data"],
+      "owner": "Target project maintainers",
+      "sourcePaths": ["docs/architext/dist"],
+      "runtime": "Static files served by any local HTTP server",
+      "interfaces": ["architext build [path]", "python3 -m http.server"],
+      "dependencies": ["viewer-runtime", "target-data-files"],
+      "dataHandled": ["architecture-model", "package-assets"],
+      "security": ["Generated artifact should remain ignored unless intentionally published"],
+      "observability": ["Build output", "Static server logs"],
+      "relatedFlows": ["static-export"],
+      "relatedDecisions": ["global-cli-data-only"],
+      "knownRisks": ["stale-static-export"],
+      "verification": ["architext build ."]
+    }
+  ]
+}