archsutra-ai 0.1.2 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/README.md +25 -17
  3. package/dist/audit.js +5 -2
  4. package/dist/cli.js +116 -12
  5. package/dist/drift.js +57 -0
  6. package/dist/imports.js +42 -0
  7. package/dist/map.js +13 -1
  8. package/dist/mcp.js +81 -0
  9. package/dist/scaffold.js +87 -0
  10. package/dist/suppress.js +51 -0
  11. package/docs/architecture/overview.html +3 -3
  12. package/docs/architecture/threat-model.html +3 -3
  13. package/docs/community/good-first-issues.html +3 -3
  14. package/docs/compatibility/matrix.html +3 -3
  15. package/docs/compatibility/smoke-tests/index.html +3 -3
  16. package/docs/compatibility/smoke-tests/results-2026-11-07.md +17 -0
  17. package/docs/decisions/ADR-0001-deterministic-cli-plus-ide-skills.html +3 -3
  18. package/docs/handbook/01-executive-summary.html +5 -5
  19. package/docs/handbook/01-executive-summary.md +2 -2
  20. package/docs/handbook/02-functional-specification.html +5 -5
  21. package/docs/handbook/02-functional-specification.md +2 -2
  22. package/docs/handbook/03-technical-specification.html +4 -4
  23. package/docs/handbook/03-technical-specification.md +1 -1
  24. package/docs/handbook/04-architecture.html +4 -4
  25. package/docs/handbook/04-architecture.md +1 -1
  26. package/docs/handbook/05-user-guide.html +6 -6
  27. package/docs/handbook/05-user-guide.md +3 -3
  28. package/docs/handbook/06-cli-reference.html +5 -5
  29. package/docs/handbook/06-cli-reference.md +9 -2
  30. package/docs/handbook/07-security-privacy-legal.html +4 -4
  31. package/docs/handbook/07-security-privacy-legal.md +1 -1
  32. package/docs/handbook/08-testing-and-proof.html +5 -5
  33. package/docs/handbook/08-testing-and-proof.md +2 -2
  34. package/docs/handbook/09-compatibility-and-roadmap.html +11 -11
  35. package/docs/handbook/09-compatibility-and-roadmap.md +25 -14
  36. package/docs/handbook/10-contributor-guide.html +4 -4
  37. package/docs/handbook/10-contributor-guide.md +3 -3
  38. package/docs/handbook/11-glossary-and-faq.html +4 -4
  39. package/docs/handbook/11-glossary-and-faq.md +1 -1
  40. package/docs/handbook/12-rule-catalog.html +3 -3
  41. package/docs/handbook/13-trust-and-assurance.html +5 -5
  42. package/docs/handbook/13-trust-and-assurance.md +3 -3
  43. package/docs/handbook/14-real-world-evaluation.html +3 -3
  44. package/docs/handbook/15-supply-chain-and-release.html +5 -5
  45. package/docs/handbook/15-supply-chain-and-release.md +7 -5
  46. package/docs/handbook/16-performance-and-quality-metrics.html +4 -4
  47. package/docs/handbook/16-performance-and-quality-metrics.md +1 -1
  48. package/docs/handbook/README.md +2 -2
  49. package/docs/handbook/index.html +5 -5
  50. package/docs/index.html +4 -4
  51. package/docs/legal/legal-review-brief.html +3 -3
  52. package/docs/legal/trademark-and-name-clearance.html +5 -5
  53. package/docs/legal/trademark-and-name-clearance.md +3 -1
  54. package/docs/proof/accessibility.html +3 -3
  55. package/docs/proof/test-results.txt +40 -35
  56. package/docs/rfc/0001-archsutra-v0.1.html +5 -5
  57. package/docs/rfc/0001-archsutra-v0.1.md +2 -2
  58. package/docs/sitemap.xml +28 -28
  59. package/llms.txt +6 -3
  60. package/package.json +7 -3
package/docs/handbook/02-functional-specification.html CHANGED
@@ -19,7 +19,7 @@
19
19
  <link rel="icon" href="../assets/favicon.svg" type="image/svg+xml">
20
20
  <link rel="stylesheet" href="../assets/site.css">
21
21
  <script>try{var t=localStorage.getItem('as-theme');if(t)document.documentElement.setAttribute('data-theme',t)}catch(e){}</script>
22
- <script type="application/ld+json">{"@context":"https://schema.org","@type":"TechArticle","headline":"Functional specification","description":"Requirement-level description of every capability, actor, input, output and acceptance test.","author":{"@type":"Person","name":"Vatsal Shah"},"inLanguage":"en","isPartOf":{"@type":"WebSite","name":"ArchSutra AI","url":"https://shahvatsalofficial.github.io/archsutra-ai"}}</script>
22
+ <script type="application/ld+json">{"@context":"https://schema.org","@type":"TechArticle","headline":"Functional specification","description":"Requirement-level description of every capability, actor, input, output and acceptance test.","author":{"@type":"Person","name":"Vatsal Shah","url":"https://shahvatsal.com"},"inLanguage":"en","isPartOf":{"@type":"WebSite","name":"ArchSutra AI","url":"https://shahvatsalofficial.github.io/archsutra-ai"}}</script>
23
23
  </head>
24
24
  <body class="doc">
25
25
  <a class="skip" href="#main">Skip to content</a>
@@ -34,7 +34,7 @@
34
34
  <div class="layout">
35
35
  <aside id="sidebar" class="sidebar" aria-label="Documentation"><div class="nav-group"><p class="nav-title">Handbook</p><ul><li><a href="../handbook/index.html">Overview</a></li><li><a href="../handbook/01-executive-summary.html">Executive summary</a></li><li><a href="../handbook/02-functional-specification.html" aria-current="page">Functional specification</a></li><li><a href="../handbook/03-technical-specification.html">Technical specification</a></li><li><a href="../handbook/04-architecture.html">Architecture</a></li><li><a href="../handbook/05-user-guide.html">User guide</a></li><li><a href="../handbook/06-cli-reference.html">CLI reference</a></li><li><a href="../handbook/07-security-privacy-legal.html">Security, privacy and legal</a></li><li><a href="../handbook/08-testing-and-proof.html">Testing and proof</a></li><li><a href="../handbook/09-compatibility-and-roadmap.html">Compatibility and roadmap</a></li><li><a href="../handbook/10-contributor-guide.html">Contributor guide</a></li><li><a href="../handbook/11-glossary-and-faq.html">Glossary and FAQ</a></li><li><a href="../handbook/12-rule-catalog.html">Audit rule catalog</a></li><li><a href="../handbook/13-trust-and-assurance.html">Trust and assurance</a></li><li><a href="../handbook/14-real-world-evaluation.html">Real-world evaluation</a></li><li><a href="../handbook/15-supply-chain-and-release.html">Supply chain and release</a></li><li><a href="../handbook/16-performance-and-quality-metrics.html">Performance and quality metrics</a></li></ul></div><div class="nav-group"><p class="nav-title">Reference</p><ul><li><a href="../architecture/overview.html">Architecture overview</a></li><li><a href="../architecture/threat-model.html">Threat model (ArchSutra CLI and skills)</a></li><li><a href="../compatibility/matrix.html">Compatibility matrix</a></li><li><a href="../rfc/0001-archsutra-v0.1.html">RFC 0001: ArchSutra AI v0.1</a></li><li><a href="../decisions/ADR-0001-deterministic-cli-plus-ide-skills.html">ADR-0001: Deterministic CLI plus IDE-native skills</a></li><li><a href="../compatibility/smoke-tests/index.html">Live smoke tests</a></li><li><a href="../community/good-first-issues.html">Good first issues (ready to file)</a></li><li><a href="../legal/trademark-and-name-clearance.html">Name and trademark clearance</a></li><li><a href="../legal/legal-review-brief.html">Legal review brief</a></li><li><a href="../proof/accessibility.html">Accessibility audit of the documentation site</a></li></ul></div></aside>
36
36
  <main id="main" class="content"><article class="prose"><p class="crumbs"><a href="../index.html">ArchSutra AI</a> / Handbook</p><h1 id="functional-specification">Functional specification</h1>
37
- <p class="lede">Requirement-level description of every capability, actor, input, output and acceptance test.</p><p class="meta">Version 0.1.2 &middot; Source: <a href="https://github.com/shahvatsalofficial/archsutra-ai/blob/main/docs/handbook/02-functional-specification.md" rel="noopener">docs/handbook/02-functional-specification.md</a></p>
37
+ <p class="lede">Requirement-level description of every capability, actor, input, output and acceptance test.</p><p class="meta">Version 0.1.4 &middot; Source: <a href="https://github.com/shahvatsalofficial/archsutra-ai/blob/main/docs/handbook/02-functional-specification.md" rel="noopener">docs/handbook/02-functional-specification.md</a></p>
38
38
  <h2 id="1-purpose-and-scope">1. Purpose and scope<a class="anchor" href="#1-purpose-and-scope" aria-label="Link to this section">#</a></h2>
39
39
  <p>ArchSutra AI helps people understand and improve the architecture of a software system. It covers <strong>audit</strong> of existing code, <strong>design</strong> of new systems, <strong>modernization</strong> planning, <strong>threat modeling</strong> and <strong>verification</strong> of architecture documents.</p>
40
40
  <p>In scope for v0.1: deterministic repository analysis, skill and agent content, installation into five AI IDEs, report export. Out of scope: server mode, model-provider runtime, local-model runtime, languages beyond import graphs for JS/TS/Python, runtime profiling. See the <a href="../rfc/0001-archsutra-v0.1.html">RFC</a>.</p>
@@ -43,7 +43,7 @@
43
43
  <h2 id="3-functional-requirements">3. Functional requirements<a class="anchor" href="#3-functional-requirements" aria-label="Link to this section">#</a></h2>
44
44
  <p>IDs are stable. &quot;Status&quot; is implemented and tested (<strong>T</strong>), implemented not live-verified (<strong>I</strong>), or planned (<strong>P</strong>).</p>
45
45
  <h3 id="31-repository-analysis-cli">3.1 Repository analysis (CLI)<a class="anchor" href="#31-repository-analysis-cli" aria-label="Link to this section">#</a></h3>
46
- <div class="table-wrap" tabindex="0" role="region" aria-label="Table 2: 3.1 Repository analysis (CLI)"><table><thead><tr><th scope="col">ID</th><th scope="col">Requirement</th><th scope="col">Status</th></tr></thead><tbody><tr><td>F-01</td><td>Walk a repository with limits (5000 files, 512 KB per file, 15 s), skipping ignored directories, binaries and symlinks, and report truncation</td><td>T</td></tr><tr><td>F-02</td><td>Detect ecosystems from manifests and file extensions (TypeScript, JavaScript, Python, Java, Kotlin, C#, Go, Rust, PHP, Ruby, Swift, Dart)</td><td>T</td></tr><tr><td>F-03</td><td>Detect frameworks and datastores from dependency manifests</td><td>T</td></tr><tr><td>F-04</td><td>Detect infrastructure files (Docker, Compose, Terraform, Kubernetes/Helm, GitHub Actions)</td><td>T</td></tr><tr><td>F-05</td><td>Build a module-level dependency graph from relative imports (JS/TS) and package imports (Python)</td><td>T</td></tr><tr><td>F-06</td><td>Detect dependency cycles between modules (Tarjan SCC)</td><td>T</td></tr><tr><td>F-07</td><td>List blind spots explicitly in every output</td><td>T</td></tr></tbody></table></div>
46
+ <div class="table-wrap" tabindex="0" role="region" aria-label="Table 2: 3.1 Repository analysis (CLI)"><table><thead><tr><th scope="col">ID</th><th scope="col">Requirement</th><th scope="col">Status</th></tr></thead><tbody><tr><td>F-01</td><td>Walk a repository with limits (5000 files, 512 KB per file, 15 s), skipping ignored directories, binaries and symlinks, and report truncation</td><td>T</td></tr><tr><td>F-02</td><td>Detect ecosystems from manifests and file extensions (TypeScript, JavaScript, Python, Java, Kotlin, C#, Go, Rust, PHP, Ruby, Swift, Dart)</td><td>T</td></tr><tr><td>F-03</td><td>Detect frameworks and datastores from dependency manifests</td><td>T</td></tr><tr><td>F-04</td><td>Detect infrastructure files (Docker, Compose, Terraform, Kubernetes/Helm, GitHub Actions)</td><td>T</td></tr><tr><td>F-05</td><td>Build a module-level dependency graph from relative imports (JS/TS), package imports (Python), and import-suffix matches (Go, Java, Kotlin, C#, Rust)</td><td>T</td></tr><tr><td>F-06</td><td>Detect dependency cycles between modules (Tarjan SCC)</td><td>T</td></tr><tr><td>F-07</td><td>List blind spots explicitly in every output</td><td>T</td></tr></tbody></table></div>
47
47
  <h3 id="32-audit">3.2 Audit<a class="anchor" href="#32-audit" aria-label="Link to this section">#</a></h3>
48
48
  <div class="table-wrap" tabindex="0" role="region" aria-label="Table 3: 3.2 Audit"><table><thead><tr><th scope="col">ID</th><th scope="col">Requirement</th><th scope="col">Status</th></tr></thead><tbody><tr><td>F-10</td><td>Evaluate 19 rules (see <a href="12-rule-catalog.html">rule catalog</a>) and emit findings</td><td>T</td></tr><tr><td>F-11</td><td>Each finding has stable ID, title, category, severity, confidence, evidence (path, line, kind, redacted excerpt), impact, why it matters, fix, verification, acceptance criteria, effort, owner type, caveats, references</td><td>T</td></tr><tr><td>F-12</td><td>Never include secret values in any output</td><td>T</td></tr><tr><td>F-13</td><td>Produce a scorecard; categories without evidence are <code>not assessed</code></td><td>T</td></tr><tr><td>F-14</td><td><code>--fail-on &lt;severity&gt;</code> returns exit code 1 when a finding meets the threshold</td><td>T</td></tr></tbody></table></div>
49
49
  <h3 id="33-reporting-and-export">3.3 Reporting and export<a class="anchor" href="#33-reporting-and-export" aria-label="Link to this section">#</a></h3>
@@ -53,7 +53,7 @@
53
53
  <h3 id="35-installation">3.5 Installation<a class="anchor" href="#35-installation" aria-label="Link to this section">#</a></h3>
54
54
  <div class="table-wrap" tabindex="0" role="region" aria-label="Table 6: 3.5 Installation"><table><thead><tr><th scope="col">ID</th><th scope="col">Requirement</th><th scope="col">Status</th></tr></thead><tbody><tr><td>F-40</td><td>Plan an install per host: create, update, unchanged, conflict</td><td>T</td></tr><tr><td>F-41</td><td>Refuse to overwrite files not installed by ArchSutra without <code>--force</code>; back up when forced</td><td>T</td></tr><tr><td>F-42</td><td>Record SHA-256 in <code>.archsutra/install-manifest.json</code>; make install idempotent</td><td>T</td></tr><tr><td>F-43</td><td>Uninstall removes only unmodified installed files and the managed <code>AGENTS.md</code> block</td><td>T</td></tr><tr><td>F-44</td><td><code>doctor</code> reports Node version, detected hosts, drift, missing files</td><td>T</td></tr><tr><td>F-45</td><td>Write only supported frontmatter for Claude and Copilot agent files</td><td>T</td></tr><tr><td>F-46</td><td>Skills load and run inside each live host</td><td>I (not verified)</td></tr></tbody></table></div>
55
55
  <h3 id="36-ai-assisted-workflows-skills">3.6 AI-assisted workflows (skills)<a class="anchor" href="#36-ai-assisted-workflows-skills" aria-label="Link to this section">#</a></h3>
56
- <div class="table-wrap" tabindex="0" role="region" aria-label="Table 7: 3.6 AI-assisted workflows (skills)"><table><thead><tr><th scope="col">ID</th><th scope="col">Workflow</th><th scope="col">Skill</th><th scope="col">Needs model</th></tr></thead><tbody><tr><td>F-50</td><td>Audit existing system</td><td><code>architecture-audit</code></td><td>yes (IDE)</td></tr><tr><td>F-51</td><td>Design new system</td><td><code>architecture-design</code></td><td>yes</td></tr><tr><td>F-52</td><td>Modernization / migration plan</td><td><code>architecture-modernization</code></td><td>yes</td></tr><tr><td>F-53</td><td>Threat model (STRIDE, LLM/agent threats)</td><td><code>threat-modeling</code></td><td>yes</td></tr><tr><td>F-54</td><td>Verify architecture artifacts</td><td><code>architecture-verification</code></td><td>yes</td></tr><tr><td>F-55</td><td>CLI refuses to fake model-dependent commands (<code>design</code>, <code>review</code>, <code>threat-model</code>, <code>modernize</code>, <code>compare</code>, <code>cost</code>, <code>drift</code>) and exits 3</td><td></td><td>no</td></tr></tbody></table></div>
56
+ <div class="table-wrap" tabindex="0" role="region" aria-label="Table 7: 3.6 AI-assisted workflows (skills)"><table><thead><tr><th scope="col">ID</th><th scope="col">Workflow</th><th scope="col">Skill</th><th scope="col">Needs model</th></tr></thead><tbody><tr><td>F-50</td><td>Audit existing system</td><td><code>architecture-audit</code></td><td>yes (IDE)</td></tr><tr><td>F-51</td><td>Design new system</td><td><code>architecture-design</code></td><td>yes</td></tr><tr><td>F-52</td><td>Modernization / migration plan</td><td><code>architecture-modernization</code></td><td>yes</td></tr><tr><td>F-53</td><td>Threat model (STRIDE, LLM/agent threats)</td><td><code>threat-modeling</code></td><td>yes</td></tr><tr><td>F-54</td><td>Verify architecture artifacts</td><td><code>architecture-verification</code></td><td>yes</td></tr><tr><td>F-55</td><td><code>design</code>, <code>review</code>, <code>threat-model</code>, <code>modernize</code>, <code>cost</code> write an evidence starter and mark undecided sections <code>unknown</code>. <code>drift</code> and <code>compare</code> diff two findings files. <code>mcp</code> serves audit, map, and drift on stdio. No model API is called</td><td></td><td>no</td></tr></tbody></table></div>
57
57
  <h3 id="37-agent-team">3.7 Agent team<a class="anchor" href="#37-agent-team" aria-label="Link to this section">#</a></h3>
58
58
  <p>Twelve roles with a fixed contract (purpose, when to invoke, inputs, tools and policy, process, outputs, quality criteria, edge cases, escalation), validated against the plugin agent standard (trigger-style description, <code>model</code>, <code>color</code>, read-only <code>tools</code>, second-person prompt): Prime, Atlas, Blueprint, Sentinel, Cloud, Data, Nexus, Neural, Scale, Ledger, Forge, Verify. Prime orchestrates; if the host cannot spawn subagents, Prime performs specialist reviews sequentially.</p>
59
59
  <h2 id="4-non-functional-requirements">4. Non-functional requirements<a class="anchor" href="#4-non-functional-requirements" aria-label="Link to this section">#</a></h2>
@@ -69,7 +69,7 @@
69
69
  </div>
70
70
  <footer class="footer">
71
71
  <div class="footer-inner">
72
- <p><strong>ArchSutra AI</strong> v0.1.2. Design. Audit. Evolve. Created by <a href="https://github.com/shahvatsalofficial" rel="noopener">Vatsal Shah</a>. Licensed under <a href="https://github.com/shahvatsalofficial/archsutra-ai/blob/main/LICENSE" rel="noopener">Apache-2.0</a>.</p>
72
+ <p><strong>ArchSutra AI</strong> v0.1.4. Design. Audit. Evolve. Created by <a href="https://shahvatsal.com" rel="noopener">Vatsal Shah</a>. Licensed under <a href="https://github.com/shahvatsalofficial/archsutra-ai/blob/main/LICENSE" rel="noopener">Apache-2.0</a>.</p>
73
73
  <p class="fine">Review aid only. Not a certification, compliance attestation, security guarantee or legal advice. Not affiliated with Anthropic, OpenAI, Cursor, GitHub or Google; product names belong to their owners. <a href="../handbook/07-security-privacy-legal.html">Legal details</a>.</p>
74
74
  </div>
75
75
  </footer>
package/docs/handbook/02-functional-specification.md CHANGED
@@ -32,7 +32,7 @@ IDs are stable. "Status" is implemented and tested (**T**), implemented not live
32
32
  | F-02 | Detect ecosystems from manifests and file extensions (TypeScript, JavaScript, Python, Java, Kotlin, C#, Go, Rust, PHP, Ruby, Swift, Dart) | T |
33
33
  | F-03 | Detect frameworks and datastores from dependency manifests | T |
34
34
  | F-04 | Detect infrastructure files (Docker, Compose, Terraform, Kubernetes/Helm, GitHub Actions) | T |
35
- | F-05 | Build a module-level dependency graph from relative imports (JS/TS) and package imports (Python) | T |
35
+ | F-05 | Build a module-level dependency graph from relative imports (JS/TS), package imports (Python), and import-suffix matches (Go, Java, Kotlin, C#, Rust) | T |
36
36
  | F-06 | Detect dependency cycles between modules (Tarjan SCC) | T |
37
37
  | F-07 | List blind spots explicitly in every output | T |
38
38
 
@@ -88,7 +88,7 @@ IDs are stable. "Status" is implemented and tested (**T**), implemented not live
88
88
  | F-52 | Modernization / migration plan | `architecture-modernization` | yes |
89
89
  | F-53 | Threat model (STRIDE, LLM/agent threats) | `threat-modeling` | yes |
90
90
  | F-54 | Verify architecture artifacts | `architecture-verification` | yes |
91
- | F-55 | CLI refuses to fake model-dependent commands (`design`, `review`, `threat-model`, `modernize`, `compare`, `cost`, `drift`) and exits 3 | | no |
91
+ | F-55 | `design`, `review`, `threat-model`, `modernize`, `cost` write an evidence starter and mark undecided sections `unknown`. `drift` and `compare` diff two findings files. `mcp` serves audit, map, and drift on stdio. No model API is called | | no |
92
92
 
93
93
  ### 3.7 Agent team
94
94
 
package/docs/handbook/03-technical-specification.html CHANGED
@@ -19,7 +19,7 @@
19
19
  <link rel="icon" href="../assets/favicon.svg" type="image/svg+xml">
20
20
  <link rel="stylesheet" href="../assets/site.css">
21
21
  <script>try{var t=localStorage.getItem('as-theme');if(t)document.documentElement.setAttribute('data-theme',t)}catch(e){}</script>
22
- <script type="application/ld+json">{"@context":"https://schema.org","@type":"TechArticle","headline":"Technical specification","description":"Module-by-module description of the implementation, data structures, algorithms, limits and extension points.","author":{"@type":"Person","name":"Vatsal Shah"},"inLanguage":"en","isPartOf":{"@type":"WebSite","name":"ArchSutra AI","url":"https://shahvatsalofficial.github.io/archsutra-ai"}}</script>
22
+ <script type="application/ld+json">{"@context":"https://schema.org","@type":"TechArticle","headline":"Technical specification","description":"Module-by-module description of the implementation, data structures, algorithms, limits and extension points.","author":{"@type":"Person","name":"Vatsal Shah","url":"https://shahvatsal.com"},"inLanguage":"en","isPartOf":{"@type":"WebSite","name":"ArchSutra AI","url":"https://shahvatsalofficial.github.io/archsutra-ai"}}</script>
23
23
  </head>
24
24
  <body class="doc">
25
25
  <a class="skip" href="#main">Skip to content</a>
@@ -34,7 +34,7 @@
34
34
  <div class="layout">
35
35
  <aside id="sidebar" class="sidebar" aria-label="Documentation"><div class="nav-group"><p class="nav-title">Handbook</p><ul><li><a href="../handbook/index.html">Overview</a></li><li><a href="../handbook/01-executive-summary.html">Executive summary</a></li><li><a href="../handbook/02-functional-specification.html">Functional specification</a></li><li><a href="../handbook/03-technical-specification.html" aria-current="page">Technical specification</a></li><li><a href="../handbook/04-architecture.html">Architecture</a></li><li><a href="../handbook/05-user-guide.html">User guide</a></li><li><a href="../handbook/06-cli-reference.html">CLI reference</a></li><li><a href="../handbook/07-security-privacy-legal.html">Security, privacy and legal</a></li><li><a href="../handbook/08-testing-and-proof.html">Testing and proof</a></li><li><a href="../handbook/09-compatibility-and-roadmap.html">Compatibility and roadmap</a></li><li><a href="../handbook/10-contributor-guide.html">Contributor guide</a></li><li><a href="../handbook/11-glossary-and-faq.html">Glossary and FAQ</a></li><li><a href="../handbook/12-rule-catalog.html">Audit rule catalog</a></li><li><a href="../handbook/13-trust-and-assurance.html">Trust and assurance</a></li><li><a href="../handbook/14-real-world-evaluation.html">Real-world evaluation</a></li><li><a href="../handbook/15-supply-chain-and-release.html">Supply chain and release</a></li><li><a href="../handbook/16-performance-and-quality-metrics.html">Performance and quality metrics</a></li></ul></div><div class="nav-group"><p class="nav-title">Reference</p><ul><li><a href="../architecture/overview.html">Architecture overview</a></li><li><a href="../architecture/threat-model.html">Threat model (ArchSutra CLI and skills)</a></li><li><a href="../compatibility/matrix.html">Compatibility matrix</a></li><li><a href="../rfc/0001-archsutra-v0.1.html">RFC 0001: ArchSutra AI v0.1</a></li><li><a href="../decisions/ADR-0001-deterministic-cli-plus-ide-skills.html">ADR-0001: Deterministic CLI plus IDE-native skills</a></li><li><a href="../compatibility/smoke-tests/index.html">Live smoke tests</a></li><li><a href="../community/good-first-issues.html">Good first issues (ready to file)</a></li><li><a href="../legal/trademark-and-name-clearance.html">Name and trademark clearance</a></li><li><a href="../legal/legal-review-brief.html">Legal review brief</a></li><li><a href="../proof/accessibility.html">Accessibility audit of the documentation site</a></li></ul></div></aside>
36
36
  <main id="main" class="content"><article class="prose"><p class="crumbs"><a href="../index.html">ArchSutra AI</a> / Handbook</p><h1 id="technical-specification">Technical specification</h1>
37
- <p class="lede">Module-by-module description of the implementation, data structures, algorithms, limits and extension points.</p><p class="meta">Version 0.1.2 &middot; Source: <a href="https://github.com/shahvatsalofficial/archsutra-ai/blob/main/docs/handbook/03-technical-specification.md" rel="noopener">docs/handbook/03-technical-specification.md</a></p>
37
+ <p class="lede">Module-by-module description of the implementation, data structures, algorithms, limits and extension points.</p><p class="meta">Version 0.1.4 &middot; Source: <a href="https://github.com/shahvatsalofficial/archsutra-ai/blob/main/docs/handbook/03-technical-specification.md" rel="noopener">docs/handbook/03-technical-specification.md</a></p>
38
38
  <h2 id="1-stack">1. Stack<a class="anchor" href="#1-stack" aria-label="Link to this section">#</a></h2>
39
39
  <div class="table-wrap" tabindex="0" role="region" aria-label="Table 1: 1. Stack"><table><thead><tr><th scope="col">Aspect</th><th scope="col">Choice</th></tr></thead><tbody><tr><td>Language</td><td>TypeScript 7.x (native compiler), <code>strict: true</code>, <code>types: [&quot;node&quot;]</code></td></tr><tr><td>Module system</td><td>ESM (<code>&quot;type&quot;: &quot;module&quot;</code>, <code>NodeNext</code>)</td></tr><tr><td>Runtime</td><td>Node.js &gt;= 20</td></tr><tr><td>Runtime dependencies</td><td>none</td></tr><tr><td>Dev dependencies</td><td><code>typescript</code> 7.x, <code>@types/node</code> 26.x (CI also runs Node 20, 22, 24 and the newest Node)</td></tr><tr><td>Test runner</td><td>built-in <code>node --test</code></td></tr><tr><td>Build</td><td><code>tsc</code> to <code>dist/</code>; <code>prepare</code> builds on install from Git</td></tr><tr><td>Entry point</td><td><code>dist/cli.js</code> (bin <code>archsutra</code>)</td></tr></tbody></table></div>
40
40
  <h2 id="2-repository-layout">2. Repository layout<a class="anchor" href="#2-repository-layout" aria-label="Link to this section">#</a></h2>
@@ -104,7 +104,7 @@ install/ thin install.sh / install.ps1 / install.cmd wrappers around npx
104
104
  <h2 id="8-build-test-release">8. Build, test, release<a class="anchor" href="#8-build-test-release" aria-label="Link to this section">#</a></h2>
105
105
  <div class="code"><button class="copy" type="button" aria-label="Copy code">Copy</button><pre tabindex="0"><code class="language-bash">npm ci
106
106
  npm run typecheck
107
- npm test # build + node --test (31 tests)
107
+ npm test # build + node --test (36 tests)
108
108
  npm run coverage # coverage report
109
109
  node scripts/realworld.mjs run &lt;dir&gt; &lt;batch&gt; [tag]
110
110
  node scripts/labeled-recall.mjs &lt;dir&gt;
@@ -118,7 +118,7 @@ node scripts/build-docs.mjs</code></pre></div>
118
118
  </div>
119
119
  <footer class="footer">
120
120
  <div class="footer-inner">
121
- <p><strong>ArchSutra AI</strong> v0.1.2. Design. Audit. Evolve. Created by <a href="https://github.com/shahvatsalofficial" rel="noopener">Vatsal Shah</a>. Licensed under <a href="https://github.com/shahvatsalofficial/archsutra-ai/blob/main/LICENSE" rel="noopener">Apache-2.0</a>.</p>
121
+ <p><strong>ArchSutra AI</strong> v0.1.4. Design. Audit. Evolve. Created by <a href="https://shahvatsal.com" rel="noopener">Vatsal Shah</a>. Licensed under <a href="https://github.com/shahvatsalofficial/archsutra-ai/blob/main/LICENSE" rel="noopener">Apache-2.0</a>.</p>
122
122
  <p class="fine">Review aid only. Not a certification, compliance attestation, security guarantee or legal advice. Not affiliated with Anthropic, OpenAI, Cursor, GitHub or Google; product names belong to their owners. <a href="../handbook/07-security-privacy-legal.html">Legal details</a>.</p>
123
123
  </div>
124
124
  </footer>
package/docs/handbook/03-technical-specification.md CHANGED
@@ -149,7 +149,7 @@ Memory: file contents are cached per run (bounded by 5000 x 512 KiB worst case,
149
149
  ```bash
150
150
  npm ci
151
151
  npm run typecheck
152
- npm test # build + node --test (31 tests)
152
+ npm test # build + node --test (36 tests)
153
153
  npm run coverage # coverage report
154
154
  node scripts/realworld.mjs run <dir> <batch> [tag]
155
155
  node scripts/labeled-recall.mjs <dir>
package/docs/handbook/04-architecture.html CHANGED
@@ -19,7 +19,7 @@
19
19
  <link rel="icon" href="../assets/favicon.svg" type="image/svg+xml">
20
20
  <link rel="stylesheet" href="../assets/site.css">
21
21
  <script>try{var t=localStorage.getItem('as-theme');if(t)document.documentElement.setAttribute('data-theme',t)}catch(e){}</script>
22
- <script type="application/ld+json">{"@context":"https://schema.org","@type":"TechArticle","headline":"Architecture","description":"C4 views, runtime flows, trust boundaries, quality attributes and the decisions behind ArchSutra AI.","author":{"@type":"Person","name":"Vatsal Shah"},"inLanguage":"en","isPartOf":{"@type":"WebSite","name":"ArchSutra AI","url":"https://shahvatsalofficial.github.io/archsutra-ai"}}</script>
22
+ <script type="application/ld+json">{"@context":"https://schema.org","@type":"TechArticle","headline":"Architecture","description":"C4 views, runtime flows, trust boundaries, quality attributes and the decisions behind ArchSutra AI.","author":{"@type":"Person","name":"Vatsal Shah","url":"https://shahvatsal.com"},"inLanguage":"en","isPartOf":{"@type":"WebSite","name":"ArchSutra AI","url":"https://shahvatsalofficial.github.io/archsutra-ai"}}</script>
23
23
  </head>
24
24
  <body class="doc">
25
25
  <a class="skip" href="#main">Skip to content</a>
@@ -34,7 +34,7 @@
34
34
  <div class="layout">
35
35
  <aside id="sidebar" class="sidebar" aria-label="Documentation"><div class="nav-group"><p class="nav-title">Handbook</p><ul><li><a href="../handbook/index.html">Overview</a></li><li><a href="../handbook/01-executive-summary.html">Executive summary</a></li><li><a href="../handbook/02-functional-specification.html">Functional specification</a></li><li><a href="../handbook/03-technical-specification.html">Technical specification</a></li><li><a href="../handbook/04-architecture.html" aria-current="page">Architecture</a></li><li><a href="../handbook/05-user-guide.html">User guide</a></li><li><a href="../handbook/06-cli-reference.html">CLI reference</a></li><li><a href="../handbook/07-security-privacy-legal.html">Security, privacy and legal</a></li><li><a href="../handbook/08-testing-and-proof.html">Testing and proof</a></li><li><a href="../handbook/09-compatibility-and-roadmap.html">Compatibility and roadmap</a></li><li><a href="../handbook/10-contributor-guide.html">Contributor guide</a></li><li><a href="../handbook/11-glossary-and-faq.html">Glossary and FAQ</a></li><li><a href="../handbook/12-rule-catalog.html">Audit rule catalog</a></li><li><a href="../handbook/13-trust-and-assurance.html">Trust and assurance</a></li><li><a href="../handbook/14-real-world-evaluation.html">Real-world evaluation</a></li><li><a href="../handbook/15-supply-chain-and-release.html">Supply chain and release</a></li><li><a href="../handbook/16-performance-and-quality-metrics.html">Performance and quality metrics</a></li></ul></div><div class="nav-group"><p class="nav-title">Reference</p><ul><li><a href="../architecture/overview.html">Architecture overview</a></li><li><a href="../architecture/threat-model.html">Threat model (ArchSutra CLI and skills)</a></li><li><a href="../compatibility/matrix.html">Compatibility matrix</a></li><li><a href="../rfc/0001-archsutra-v0.1.html">RFC 0001: ArchSutra AI v0.1</a></li><li><a href="../decisions/ADR-0001-deterministic-cli-plus-ide-skills.html">ADR-0001: Deterministic CLI plus IDE-native skills</a></li><li><a href="../compatibility/smoke-tests/index.html">Live smoke tests</a></li><li><a href="../community/good-first-issues.html">Good first issues (ready to file)</a></li><li><a href="../legal/trademark-and-name-clearance.html">Name and trademark clearance</a></li><li><a href="../legal/legal-review-brief.html">Legal review brief</a></li><li><a href="../proof/accessibility.html">Accessibility audit of the documentation site</a></li></ul></div></aside>
36
36
  <main id="main" class="content"><article class="prose"><p class="crumbs"><a href="../index.html">ArchSutra AI</a> / Handbook</p><h1 id="architecture">Architecture</h1>
37
- <p class="lede">C4 views, runtime flows, trust boundaries, quality attributes and the decisions behind ArchSutra AI.</p><p class="meta">Version 0.1.2 &middot; Source: <a href="https://github.com/shahvatsalofficial/archsutra-ai/blob/main/docs/handbook/04-architecture.md" rel="noopener">docs/handbook/04-architecture.md</a></p>
37
+ <p class="lede">C4 views, runtime flows, trust boundaries, quality attributes and the decisions behind ArchSutra AI.</p><p class="meta">Version 0.1.4 &middot; Source: <a href="https://github.com/shahvatsalofficial/archsutra-ai/blob/main/docs/handbook/04-architecture.md" rel="noopener">docs/handbook/04-architecture.md</a></p>
38
38
  <p>Notation: C4 model (Context, Container, Component), diagrams in Mermaid. Every element corresponds to something in the repository.</p>
39
39
  <h2 id="1-system-context-c4-level-1">1. System context (C4 level 1)<a class="anchor" href="#1-system-context-c4-level-1" aria-label="Link to this section">#</a></h2>
40
40
  <figure class="diagram"><pre class="mermaid">flowchart TB
@@ -142,7 +142,7 @@
142
142
  repo -. &quot;may contain injected text&quot; .-&gt; ide</pre><figcaption>Diagram (Mermaid). If it does not render, the source is shown above.</figcaption></figure>
143
143
  <p>Controls and residual risk are in the <a href="../architecture/threat-model.html">threat model</a>.</p>
144
144
  <h2 id="6-quality-attributes">6. Quality attributes<a class="anchor" href="#6-quality-attributes" aria-label="Link to this section">#</a></h2>
145
- <div class="table-wrap" tabindex="0" role="region" aria-label="Table 2: 6. Quality attributes"><table><thead><tr><th scope="col">Attribute</th><th scope="col">Strategy</th><th scope="col">Verified by</th></tr></thead><tbody><tr><td>Security</td><td>read-only default, redaction, containment, hashed installs</td><td>security tests</td></tr><tr><td>Privacy</td><td>offline, no telemetry</td><td>design + code review</td></tr><tr><td>Reliability</td><td>skip-on-error scanning, bounded work</td><td>limit tests</td></tr><tr><td>Portability</td><td>Node only, no shell dependency in core</td><td>3-OS CI</td></tr><tr><td>Maintainability</td><td>small modules, acyclic, typed</td><td>self-audit, typecheck</td></tr><tr><td>Testability</td><td>pure render functions, runtime-built fixtures</td><td>31 tests</td></tr><tr><td>Extensibility</td><td>declarative host table, rule table, agent contract</td><td>contributor guide</td></tr><tr><td>Honesty</td><td>support levels, <code>not assessed</code>, caveats on every finding</td><td>review</td></tr></tbody></table></div>
145
+ <div class="table-wrap" tabindex="0" role="region" aria-label="Table 2: 6. Quality attributes"><table><thead><tr><th scope="col">Attribute</th><th scope="col">Strategy</th><th scope="col">Verified by</th></tr></thead><tbody><tr><td>Security</td><td>read-only default, redaction, containment, hashed installs</td><td>security tests</td></tr><tr><td>Privacy</td><td>offline, no telemetry</td><td>design + code review</td></tr><tr><td>Reliability</td><td>skip-on-error scanning, bounded work</td><td>limit tests</td></tr><tr><td>Portability</td><td>Node only, no shell dependency in core</td><td>3-OS CI</td></tr><tr><td>Maintainability</td><td>small modules, acyclic, typed</td><td>self-audit, typecheck</td></tr><tr><td>Testability</td><td>pure render functions, runtime-built fixtures</td><td>36 tests</td></tr><tr><td>Extensibility</td><td>declarative host table, rule table, agent contract</td><td>contributor guide</td></tr><tr><td>Honesty</td><td>support levels, <code>not assessed</code>, caveats on every finding</td><td>review</td></tr></tbody></table></div>
146
146
  <h2 id="7-architectural-decisions">7. Architectural decisions<a class="anchor" href="#7-architectural-decisions" aria-label="Link to this section">#</a></h2>
147
147
  <div class="table-wrap" tabindex="0" role="region" aria-label="Table 3: 7. Architectural decisions"><table><thead><tr><th scope="col">ADR</th><th scope="col">Decision</th></tr></thead><tbody><tr><td><a href="../decisions/ADR-0001-deterministic-cli-plus-ide-skills.html">ADR-0001</a></td><td>Deterministic CLI for evidence plus IDE-native skills for reasoning; no server, no API key</td></tr></tbody></table></div>
148
148
  <p>Additional decisions captured in the <a href="../rfc/0001-archsutra-v0.1.html">RFC</a>: single canonical source with generated host layouts; honest capability labels; zero runtime dependencies; module-level (not file-level) dependency graph for stability.</p>
@@ -154,7 +154,7 @@
154
154
  </div>
155
155
  <footer class="footer">
156
156
  <div class="footer-inner">
157
- <p><strong>ArchSutra AI</strong> v0.1.2. Design. Audit. Evolve. Created by <a href="https://github.com/shahvatsalofficial" rel="noopener">Vatsal Shah</a>. Licensed under <a href="https://github.com/shahvatsalofficial/archsutra-ai/blob/main/LICENSE" rel="noopener">Apache-2.0</a>.</p>
157
+ <p><strong>ArchSutra AI</strong> v0.1.4. Design. Audit. Evolve. Created by <a href="https://shahvatsal.com" rel="noopener">Vatsal Shah</a>. Licensed under <a href="https://github.com/shahvatsalofficial/archsutra-ai/blob/main/LICENSE" rel="noopener">Apache-2.0</a>.</p>
158
158
  <p class="fine">Review aid only. Not a certification, compliance attestation, security guarantee or legal advice. Not affiliated with Anthropic, OpenAI, Cursor, GitHub or Google; product names belong to their owners. <a href="../handbook/07-security-privacy-legal.html">Legal details</a>.</p>
159
159
  </div>
160
160
  </footer>
package/docs/handbook/04-architecture.md CHANGED
@@ -158,7 +158,7 @@ Controls and residual risk are in the [threat model](../architecture/threat-mode
158
158
  | Reliability | skip-on-error scanning, bounded work | limit tests |
159
159
  | Portability | Node only, no shell dependency in core | 3-OS CI |
160
160
  | Maintainability | small modules, acyclic, typed | self-audit, typecheck |
161
- | Testability | pure render functions, runtime-built fixtures | 31 tests |
161
+ | Testability | pure render functions, runtime-built fixtures | 36 tests |
162
162
  | Extensibility | declarative host table, rule table, agent contract | contributor guide |
163
163
  | Honesty | support levels, `not assessed`, caveats on every finding | review |
164
164
 
package/docs/handbook/05-user-guide.html CHANGED
@@ -19,7 +19,7 @@
19
19
  <link rel="icon" href="../assets/favicon.svg" type="image/svg+xml">
20
20
  <link rel="stylesheet" href="../assets/site.css">
21
21
  <script>try{var t=localStorage.getItem('as-theme');if(t)document.documentElement.setAttribute('data-theme',t)}catch(e){}</script>
22
- <script type="application/ld+json">{"@context":"https://schema.org","@type":"TechArticle","headline":"User guide","description":"Install, run your first audit, use the skills in your AI IDE, wire it into CI, and fix common problems.","author":{"@type":"Person","name":"Vatsal Shah"},"inLanguage":"en","isPartOf":{"@type":"WebSite","name":"ArchSutra AI","url":"https://shahvatsalofficial.github.io/archsutra-ai"}}</script>
22
+ <script type="application/ld+json">{"@context":"https://schema.org","@type":"TechArticle","headline":"User guide","description":"Install, run your first audit, use the skills in your AI IDE, wire it into CI, and fix common problems.","author":{"@type":"Person","name":"Vatsal Shah","url":"https://shahvatsal.com"},"inLanguage":"en","isPartOf":{"@type":"WebSite","name":"ArchSutra AI","url":"https://shahvatsalofficial.github.io/archsutra-ai"}}</script>
23
23
  </head>
24
24
  <body class="doc">
25
25
  <a class="skip" href="#main">Skip to content</a>
@@ -34,7 +34,7 @@
34
34
  <div class="layout">
35
35
  <aside id="sidebar" class="sidebar" aria-label="Documentation"><div class="nav-group"><p class="nav-title">Handbook</p><ul><li><a href="../handbook/index.html">Overview</a></li><li><a href="../handbook/01-executive-summary.html">Executive summary</a></li><li><a href="../handbook/02-functional-specification.html">Functional specification</a></li><li><a href="../handbook/03-technical-specification.html">Technical specification</a></li><li><a href="../handbook/04-architecture.html">Architecture</a></li><li><a href="../handbook/05-user-guide.html" aria-current="page">User guide</a></li><li><a href="../handbook/06-cli-reference.html">CLI reference</a></li><li><a href="../handbook/07-security-privacy-legal.html">Security, privacy and legal</a></li><li><a href="../handbook/08-testing-and-proof.html">Testing and proof</a></li><li><a href="../handbook/09-compatibility-and-roadmap.html">Compatibility and roadmap</a></li><li><a href="../handbook/10-contributor-guide.html">Contributor guide</a></li><li><a href="../handbook/11-glossary-and-faq.html">Glossary and FAQ</a></li><li><a href="../handbook/12-rule-catalog.html">Audit rule catalog</a></li><li><a href="../handbook/13-trust-and-assurance.html">Trust and assurance</a></li><li><a href="../handbook/14-real-world-evaluation.html">Real-world evaluation</a></li><li><a href="../handbook/15-supply-chain-and-release.html">Supply chain and release</a></li><li><a href="../handbook/16-performance-and-quality-metrics.html">Performance and quality metrics</a></li></ul></div><div class="nav-group"><p class="nav-title">Reference</p><ul><li><a href="../architecture/overview.html">Architecture overview</a></li><li><a href="../architecture/threat-model.html">Threat model (ArchSutra CLI and skills)</a></li><li><a href="../compatibility/matrix.html">Compatibility matrix</a></li><li><a href="../rfc/0001-archsutra-v0.1.html">RFC 0001: ArchSutra AI v0.1</a></li><li><a href="../decisions/ADR-0001-deterministic-cli-plus-ide-skills.html">ADR-0001: Deterministic CLI plus IDE-native skills</a></li><li><a href="../compatibility/smoke-tests/index.html">Live smoke tests</a></li><li><a href="../community/good-first-issues.html">Good first issues (ready to file)</a></li><li><a href="../legal/trademark-and-name-clearance.html">Name and trademark clearance</a></li><li><a href="../legal/legal-review-brief.html">Legal review brief</a></li><li><a href="../proof/accessibility.html">Accessibility audit of the documentation site</a></li></ul></div></aside>
36
36
  <main id="main" class="content"><article class="prose"><p class="crumbs"><a href="../index.html">ArchSutra AI</a> / Handbook</p><h1 id="user-guide">User guide</h1>
37
- <p class="lede">Install, run your first audit, use the skills in your AI IDE, wire it into CI, and fix common problems.</p><p class="meta">Version 0.1.2 &middot; Source: <a href="https://github.com/shahvatsalofficial/archsutra-ai/blob/main/docs/handbook/05-user-guide.md" rel="noopener">docs/handbook/05-user-guide.md</a></p>
37
+ <p class="lede">Install, run your first audit, use the skills in your AI IDE, wire it into CI, and fix common problems.</p><p class="meta">Version 0.1.4 &middot; Source: <a href="https://github.com/shahvatsalofficial/archsutra-ai/blob/main/docs/handbook/05-user-guide.md" rel="noopener">docs/handbook/05-user-guide.md</a></p>
38
38
  <h2 id="1-requirements">1. Requirements<a class="anchor" href="#1-requirements" aria-label="Link to this section">#</a></h2>
39
39
  <ul><li>Node.js 20 or newer (<code>node -v</code>).</li><li>Git (only if you install from GitHub).</li><li>Optional: one supported AI IDE to use the skills.</li></ul>
40
40
  <p>No account, API key, or network access is needed to run the CLI.</p>
@@ -86,11 +86,11 @@ jobs:
86
86
  - uses: actions/checkout@v4
87
87
  - uses: actions/setup-node@v4
88
88
  with: { node-version: 22 }
89
- - run: npx --yes github:shahvatsalofficial/archsutra-ai audit . --fail-on high
90
- - run: npx --yes github:shahvatsalofficial/archsutra-ai export . --output arch-report
89
+ - run: npx --yes archsutra-ai@0.1.3 audit . --fail-on high
90
+ - run: npx --yes archsutra-ai@0.1.3 export . --output arch-report
91
91
  - uses: github/codeql-action/upload-sarif@v3
92
92
  with: { sarif_file: arch-report/findings.sarif }</code></pre></div>
93
- <p>Pin the package to a tag or, better, a full commit SHA in production pipelines (<code>github:shahvatsalofficial/archsutra-ai#v0.1.1</code>). Release tarballs carry checksums and a provenance attestation: see <a href="15-supply-chain-and-release.html">Supply chain and release</a>.</p>
93
+ <p>The snippet above is an illustration. Workflows in this repository pin each Action to a commit SHA. Pin production pipelines to <code>archsutra-ai@0.1.3</code> (both command names, including Windows). The git tag <code>v0.1.2</code> is the attested GitHub release and its bin is only <code>archsutra</code>. Do not pin <code>v0.1.1</code>. There is no <code>v0.1.3</code> git tag. Release tarballs for tagged versions carry checksums and a GitHub attestation: see <a href="15-supply-chain-and-release.html">Supply chain and release</a>. npm <code>0.1.3</code> does not.</p>
94
94
  <h2 id="8-reading-a-finding">8. Reading a finding<a class="anchor" href="#8-reading-a-finding" aria-label="Link to this section">#</a></h2>
95
95
  <div class="code"><button class="copy" type="button" aria-label="Copy code">Copy</button><pre tabindex="0"><code class="language-text">AS-SEC-005#002 high SQL built by string concatenation or interpolation
96
96
  Evidence: [observed] src/services/user.ts:2
@@ -107,7 +107,7 @@ jobs:
107
107
  </div>
108
108
  <footer class="footer">
109
109
  <div class="footer-inner">
110
- <p><strong>ArchSutra AI</strong> v0.1.2. Design. Audit. Evolve. Created by <a href="https://github.com/shahvatsalofficial" rel="noopener">Vatsal Shah</a>. Licensed under <a href="https://github.com/shahvatsalofficial/archsutra-ai/blob/main/LICENSE" rel="noopener">Apache-2.0</a>.</p>
110
+ <p><strong>ArchSutra AI</strong> v0.1.4. Design. Audit. Evolve. Created by <a href="https://shahvatsal.com" rel="noopener">Vatsal Shah</a>. Licensed under <a href="https://github.com/shahvatsalofficial/archsutra-ai/blob/main/LICENSE" rel="noopener">Apache-2.0</a>.</p>
111
111
  <p class="fine">Review aid only. Not a certification, compliance attestation, security guarantee or legal advice. Not affiliated with Anthropic, OpenAI, Cursor, GitHub or Google; product names belong to their owners. <a href="../handbook/07-security-privacy-legal.html">Legal details</a>.</p>
112
112
  </div>
113
113
  </footer>
package/docs/handbook/05-user-guide.md CHANGED
@@ -119,13 +119,13 @@ jobs:
119
119
  - uses: actions/checkout@v4
120
120
  - uses: actions/setup-node@v4
121
121
  with: { node-version: 22 }
122
- - run: npx --yes github:shahvatsalofficial/archsutra-ai audit . --fail-on high
123
- - run: npx --yes github:shahvatsalofficial/archsutra-ai export . --output arch-report
122
+ - run: npx --yes archsutra-ai@0.1.3 audit . --fail-on high
123
+ - run: npx --yes archsutra-ai@0.1.3 export . --output arch-report
124
124
  - uses: github/codeql-action/upload-sarif@v3
125
125
  with: { sarif_file: arch-report/findings.sarif }
126
126
  ```
127
127
 
128
- Pin the package to a tag or, better, a full commit SHA in production pipelines (`github:shahvatsalofficial/archsutra-ai#v0.1.1`). Release tarballs carry checksums and a provenance attestation: see [Supply chain and release](15-supply-chain-and-release.md).
128
+ The snippet above is an illustration. Workflows in this repository pin each Action to a commit SHA. Pin production pipelines to `archsutra-ai@0.1.3` (both command names, including Windows). The git tag `v0.1.2` is the attested GitHub release and its bin is only `archsutra`. Do not pin `v0.1.1`. There is no `v0.1.3` git tag. Release tarballs for tagged versions carry checksums and a GitHub attestation: see [Supply chain and release](15-supply-chain-and-release.md). npm `0.1.3` does not.
129
129
 
130
130
  ## 8. Reading a finding
131
131
 
package/docs/handbook/06-cli-reference.html CHANGED
@@ -19,7 +19,7 @@
19
19
  <link rel="icon" href="../assets/favicon.svg" type="image/svg+xml">
20
20
  <link rel="stylesheet" href="../assets/site.css">
21
21
  <script>try{var t=localStorage.getItem('as-theme');if(t)document.documentElement.setAttribute('data-theme',t)}catch(e){}</script>
22
- <script type="application/ld+json">{"@context":"https://schema.org","@type":"TechArticle","headline":"CLI reference","description":"Every command, option, exit code and output file of the archsutra CLI.","author":{"@type":"Person","name":"Vatsal Shah"},"inLanguage":"en","isPartOf":{"@type":"WebSite","name":"ArchSutra AI","url":"https://shahvatsalofficial.github.io/archsutra-ai"}}</script>
22
+ <script type="application/ld+json">{"@context":"https://schema.org","@type":"TechArticle","headline":"CLI reference","description":"Every command, option, exit code and output file of the archsutra CLI.","author":{"@type":"Person","name":"Vatsal Shah","url":"https://shahvatsal.com"},"inLanguage":"en","isPartOf":{"@type":"WebSite","name":"ArchSutra AI","url":"https://shahvatsalofficial.github.io/archsutra-ai"}}</script>
23
23
  </head>
24
24
  <body class="doc">
25
25
  <a class="skip" href="#main">Skip to content</a>
@@ -34,15 +34,15 @@
34
34
  <div class="layout">
35
35
  <aside id="sidebar" class="sidebar" aria-label="Documentation"><div class="nav-group"><p class="nav-title">Handbook</p><ul><li><a href="../handbook/index.html">Overview</a></li><li><a href="../handbook/01-executive-summary.html">Executive summary</a></li><li><a href="../handbook/02-functional-specification.html">Functional specification</a></li><li><a href="../handbook/03-technical-specification.html">Technical specification</a></li><li><a href="../handbook/04-architecture.html">Architecture</a></li><li><a href="../handbook/05-user-guide.html">User guide</a></li><li><a href="../handbook/06-cli-reference.html" aria-current="page">CLI reference</a></li><li><a href="../handbook/07-security-privacy-legal.html">Security, privacy and legal</a></li><li><a href="../handbook/08-testing-and-proof.html">Testing and proof</a></li><li><a href="../handbook/09-compatibility-and-roadmap.html">Compatibility and roadmap</a></li><li><a href="../handbook/10-contributor-guide.html">Contributor guide</a></li><li><a href="../handbook/11-glossary-and-faq.html">Glossary and FAQ</a></li><li><a href="../handbook/12-rule-catalog.html">Audit rule catalog</a></li><li><a href="../handbook/13-trust-and-assurance.html">Trust and assurance</a></li><li><a href="../handbook/14-real-world-evaluation.html">Real-world evaluation</a></li><li><a href="../handbook/15-supply-chain-and-release.html">Supply chain and release</a></li><li><a href="../handbook/16-performance-and-quality-metrics.html">Performance and quality metrics</a></li></ul></div><div class="nav-group"><p class="nav-title">Reference</p><ul><li><a href="../architecture/overview.html">Architecture overview</a></li><li><a href="../architecture/threat-model.html">Threat model (ArchSutra CLI and skills)</a></li><li><a href="../compatibility/matrix.html">Compatibility matrix</a></li><li><a href="../rfc/0001-archsutra-v0.1.html">RFC 0001: ArchSutra AI v0.1</a></li><li><a href="../decisions/ADR-0001-deterministic-cli-plus-ide-skills.html">ADR-0001: Deterministic CLI plus IDE-native skills</a></li><li><a href="../compatibility/smoke-tests/index.html">Live smoke tests</a></li><li><a href="../community/good-first-issues.html">Good first issues (ready to file)</a></li><li><a href="../legal/trademark-and-name-clearance.html">Name and trademark clearance</a></li><li><a href="../legal/legal-review-brief.html">Legal review brief</a></li><li><a href="../proof/accessibility.html">Accessibility audit of the documentation site</a></li></ul></div></aside>
36
36
  <main id="main" class="content"><article class="prose"><p class="crumbs"><a href="../index.html">ArchSutra AI</a> / Handbook</p><h1 id="cli-reference">CLI reference</h1>
37
- <p class="lede">Every command, option, exit code and output file of the archsutra CLI.</p><p class="meta">Version 0.1.2 &middot; Source: <a href="https://github.com/shahvatsalofficial/archsutra-ai/blob/main/docs/handbook/06-cli-reference.md" rel="noopener">docs/handbook/06-cli-reference.md</a></p>
37
+ <p class="lede">Every command, option, exit code and output file of the archsutra CLI.</p><p class="meta">Version 0.1.4 &middot; Source: <a href="https://github.com/shahvatsalofficial/archsutra-ai/blob/main/docs/handbook/06-cli-reference.md" rel="noopener">docs/handbook/06-cli-reference.md</a></p>
38
38
  <div class="code"><button class="copy" type="button" aria-label="Copy code">Copy</button><pre tabindex="0"><code class="language-text">archsutra &lt;command&gt; [path] [options]</code></pre></div>
39
39
  <p><code>path</code> defaults to the current directory.</p>
40
40
  <h2 id="commands">Commands<a class="anchor" href="#commands" aria-label="Link to this section">#</a></h2>
41
- <div class="table-wrap" tabindex="0" role="region" aria-label="Table 1: Commands"><table><thead><tr><th scope="col">Command</th><th scope="col">Writes files?</th><th scope="col">Needs model?</th><th scope="col">Description</th></tr></thead><tbody><tr><td><code>init [path]</code></td><td>no</td><td>no</td><td>Detect the project and AI hosts; print an install plan per detected host</td></tr><tr><td><code>doctor [path]</code></td><td>no</td><td>no</td><td>Check Node, hosts, install drift, duplicate <code>AGENTS.md</code> blocks</td></tr><tr><td><code>map [path]</code></td><td>only with <code>--output</code></td><td>no</td><td>Current-state report. With <code>--output</code>, writes <code>current-state.md</code> and <code>current-state.html</code>. Otherwise prints one format</td></tr><tr><td><code>audit [path]</code></td><td>only with <code>--output</code></td><td>no</td><td>Run the rules. With <code>--output</code>, writes every report as Markdown and HTML (same set as <code>export</code>). Otherwise prints one format or JSON</td></tr><tr><td><code>verify [path]</code></td><td>no</td><td>no</td><td>Validate skills, agents, links, diagrams, <code>findings.json</code></td></tr><tr><td><code>export [path]</code></td><td>yes (in <code>--output</code>)</td><td>no</td><td>Write the documentation set. Every human report is both Markdown and HTML</td></tr><tr><td><code>html &lt;file.md&gt;</code></td><td>yes</td><td>no</td><td>Render a narrative Markdown report to a self-contained HTML page (default: sibling <code>.html</code>)</td></tr><tr><td><code>install</code></td><td>yes</td><td>no</td><td>Install skills/agents for <code>--host</code> into <code>--target</code></td></tr><tr><td><code>uninstall</code></td><td>yes</td><td>no</td><td>Remove files this tool installed</td></tr><tr><td><code>hosts</code></td><td>no</td><td>no</td><td>List adapters and support levels</td></tr><tr><td><code>version</code></td><td>no</td><td>no</td><td>Print version</td></tr><tr><td><code>design</code>, <code>review</code>, <code>threat-model</code>, <code>modernize</code>, <code>compare</code>, <code>cost</code>, <code>drift</code></td><td>no</td><td><strong>yes</strong></td><td>Exit 3 and point to the skill. No API call is made</td></tr></tbody></table></div>
41
+ <div class="table-wrap" tabindex="0" role="region" aria-label="Table 1: Commands"><table><thead><tr><th scope="col">Command</th><th scope="col">Writes files?</th><th scope="col">Needs model?</th><th scope="col">Description</th></tr></thead><tbody><tr><td><code>init [path]</code></td><td>no</td><td>no</td><td>Detect the project and AI hosts; print an install plan per detected host</td></tr><tr><td><code>doctor [path]</code></td><td>no</td><td>no</td><td>Check Node, hosts, install drift, duplicate <code>AGENTS.md</code> blocks</td></tr><tr><td><code>map [path]</code></td><td>only with <code>--output</code></td><td>no</td><td>Current-state report. With <code>--output</code>, writes <code>current-state.md</code> and <code>current-state.html</code>. Otherwise prints one format</td></tr><tr><td><code>audit [path]</code></td><td>only with <code>--output</code></td><td>no</td><td>Run the rules. With <code>--output</code>, writes every report as Markdown and HTML (same set as <code>export</code>). Otherwise prints one format or JSON</td></tr><tr><td><code>verify [path]</code></td><td>no</td><td>no</td><td>Validate skills, agents, links, diagrams, <code>findings.json</code></td></tr><tr><td><code>export [path]</code></td><td>yes (in <code>--output</code>)</td><td>no</td><td>Write the documentation set. Every human report is both Markdown and HTML</td></tr><tr><td><code>html &lt;file.md&gt;</code></td><td>yes</td><td>no</td><td>Render a narrative Markdown report to a self-contained HTML page (default: sibling <code>.html</code>)</td></tr><tr><td><code>install</code></td><td>yes</td><td>no</td><td>Install skills/agents for <code>--host</code> into <code>--target</code></td></tr><tr><td><code>uninstall</code></td><td>yes</td><td>no</td><td>Remove files this tool installed</td></tr><tr><td><code>hosts</code></td><td>no</td><td>no</td><td>List adapters and support levels</td></tr><tr><td><code>version</code></td><td>no</td><td>no</td><td>Print version</td></tr><tr><td><code>review [path]</code></td><td>with <code>--output</code></td><td>no</td><td>Evidence review starter. Same findings as <code>audit</code>. <code>--fail-on</code> works</td></tr><tr><td><code>design [path]</code></td><td>with <code>--output</code></td><td>no</td><td>Design starter from the module map. Decisions stay <code>unknown</code></td></tr><tr><td><code>threat-model [path]</code></td><td>with <code>--output</code></td><td>no</td><td>Security findings as observed rows. STRIDE completion stays <code>unknown</code></td></tr><tr><td><code>modernize [path]</code></td><td>with <code>--output</code></td><td>no</td><td>One slice per finding. Target architecture stays <code>unknown</code></td></tr><tr><td><code>cost [path]</code></td><td>with <code>--output</code></td><td>no</td><td>States that cost is not assessed</td></tr><tr><td><code>drift</code></td><td>with <code>--output</code></td><td>no</td><td>Diff two <code>findings.json</code> files, or a project against <code>--baseline</code></td></tr><tr><td><code>compare</code></td><td>with <code>--output</code></td><td>no</td><td>Same diff as <code>drift</code>. Does not run Semgrep</td></tr><tr><td><code>mcp</code></td><td>no</td><td>no</td><td>MCP server on stdio. Tools: <code>archsutra_audit</code>, <code>archsutra_map</code>, <code>archsutra_drift</code></td></tr></tbody></table></div>
42
42
  <h2 id="options">Options<a class="anchor" href="#options" aria-label="Link to this section">#</a></h2>
43
43
  <div class="table-wrap" tabindex="0" role="region" aria-label="Table 2: Options"><table><thead><tr><th scope="col">Option</th><th scope="col">Applies to</th><th scope="col">Meaning</th></tr></thead><tbody><tr><td><code>--json</code></td><td>most</td><td>Machine-readable output</td></tr><tr><td><code>--format &lt;md\|html&gt;</code></td><td><code>audit</code>, <code>map</code></td><td>Stdout format when not writing files (default <code>md</code>). Ignored for the file set: <code>--output</code> always writes both</td></tr><tr><td><code>--dry-run</code></td><td><code>audit</code>, <code>map</code>, <code>export</code>, <code>html</code>, <code>install</code>, <code>uninstall</code></td><td>Show what would change; write nothing</td></tr><tr><td><code>--output &lt;dir&gt;</code></td><td><code>audit</code>, <code>map</code>, <code>export</code></td><td>Directory inside the project (<code>export</code> default <code>docs/architecture</code>). <code>audit</code> writes the full set; <code>map</code> writes the current-state pair. Paths that escape the project are rejected</td></tr><tr><td><code>--output &lt;file.html&gt;</code></td><td><code>html</code></td><td>Destination HTML file. Default is the Markdown path with <code>.html</code></td></tr><tr><td><code>--host &lt;id&gt;</code></td><td><code>install</code>, <code>uninstall</code></td><td><code>claude</code>, <code>cursor</code>, <code>codex</code>, <code>copilot</code>, <code>gemini</code></td></tr><tr><td><code>--target &lt;dir&gt;</code></td><td><code>install</code>, <code>uninstall</code></td><td>Project to modify (default <code>.</code>)</td></tr><tr><td><code>--force</code></td><td><code>install</code></td><td>Overwrite conflicting files after backing them up</td></tr><tr><td><code>--fail-on &lt;sev&gt;</code></td><td><code>audit</code></td><td>Exit 1 if any finding is at or above <code>critical</code>, <code>high</code>, <code>medium</code> or <code>low</code></td></tr><tr><td><code>--verbose</code></td><td>all</td><td>Extra detail; stack trace on internal error</td></tr><tr><td><code>--version</code>, <code>--help</code></td><td>all</td><td></td></tr></tbody></table></div>
44
44
  <h2 id="exit-codes">Exit codes<a class="anchor" href="#exit-codes" aria-label="Link to this section">#</a></h2>
45
- <div class="table-wrap" tabindex="0" role="region" aria-label="Table 3: Exit codes"><table><thead><tr><th scope="col">Code</th><th scope="col">Name</th><th scope="col">When</th></tr></thead><tbody><tr><td>0</td><td>ok</td><td>success</td></tr><tr><td>1</td><td>findings</td><td><code>--fail-on</code> threshold met, install blocked by conflict, or <code>doctor</code> found a problem</td></tr><tr><td>2</td><td>usage</td><td>unknown command, missing <code>--host</code>, invalid <code>--fail-on</code>, <code>--output</code> escaping the project</td></tr><tr><td>3</td><td>needs model</td><td>a model-dependent command was invoked in the CLI</td></tr><tr><td>4</td><td>verify failed</td><td>at least one <code>verify</code> check failed</td></tr><tr><td>5</td><td>error</td><td>unexpected internal error</td></tr></tbody></table></div>
45
+ <div class="table-wrap" tabindex="0" role="region" aria-label="Table 3: Exit codes"><table><thead><tr><th scope="col">Code</th><th scope="col">Name</th><th scope="col">When</th></tr></thead><tbody><tr><td>0</td><td>ok</td><td>success</td></tr><tr><td>1</td><td>findings</td><td><code>--fail-on</code> threshold met, install blocked by conflict, or <code>doctor</code> found a problem</td></tr><tr><td>2</td><td>usage</td><td>unknown command, missing <code>--host</code>, invalid <code>--fail-on</code>, <code>--output</code> escaping the project</td></tr><tr><td>3</td><td>reserved</td><td>no current command returns 3. Starter commands write evidence and mark the rest <code>unknown</code></td></tr><tr><td>4</td><td>verify failed</td><td>at least one <code>verify</code> check failed</td></tr><tr><td>5</td><td>error</td><td>unexpected internal error</td></tr></tbody></table></div>
46
46
  <h2 id="output-files-from-export">Output files from <code>export</code><a class="anchor" href="#output-files-from-export" aria-label="Link to this section">#</a></h2>
47
47
  <div class="table-wrap" tabindex="0" role="region" aria-label="Table 4: Output files from export"><table><thead><tr><th scope="col">File</th><th scope="col">Format</th><th scope="col">Contents</th></tr></thead><tbody><tr><td><code>index.html</code></td><td>HTML</td><td>Overview page linking every report (open this first in a browser)</td></tr><tr><td><code>README.md</code></td><td>Markdown</td><td>Index of the set</td></tr><tr><td><code>current-state.md</code> / <code>current-state.html</code></td><td>Markdown + Mermaid / HTML</td><td>Stack, C4-style context and module diagrams, module table, cycles, blind spots</td></tr><tr><td><code>audit-report.md</code> / <code>audit-report.html</code></td><td>Markdown / HTML</td><td>Summary, scorecard, findings, scope and blind spots. The HTML version has severity cards, a severity filter and collapsible findings</td></tr><tr><td><code>findings.json</code></td><td>JSON, schema 1.0.0</td><td>Findings, scorecard, coverage, blind spots, failed checks</td></tr><tr><td><code>findings.sarif</code></td><td>SARIF 2.1.0</td><td>One result per evidence location</td></tr><tr><td><code>architecture-register.json</code></td><td>JSON</td><td>Artifact list with SHA-256 hashes and timestamp</td></tr></tbody></table></div>
48
48
  <p>Real examples: <a href="https://github.com/shahvatsalofficial/archsutra-ai/blob/main/examples/brownfield-monolith/sample-output/audit-report.md" rel="noopener"><code>examples/brownfield-monolith/sample-output/</code></a>.</p>
@@ -65,7 +65,7 @@ archsutra verify .</code></pre></div>
65
65
  </div>
66
66
  <footer class="footer">
67
67
  <div class="footer-inner">
68
- <p><strong>ArchSutra AI</strong> v0.1.2. Design. Audit. Evolve. Created by <a href="https://github.com/shahvatsalofficial" rel="noopener">Vatsal Shah</a>. Licensed under <a href="https://github.com/shahvatsalofficial/archsutra-ai/blob/main/LICENSE" rel="noopener">Apache-2.0</a>.</p>
68
+ <p><strong>ArchSutra AI</strong> v0.1.4. Design. Audit. Evolve. Created by <a href="https://shahvatsal.com" rel="noopener">Vatsal Shah</a>. Licensed under <a href="https://github.com/shahvatsalofficial/archsutra-ai/blob/main/LICENSE" rel="noopener">Apache-2.0</a>.</p>
69
69
  <p class="fine">Review aid only. Not a certification, compliance attestation, security guarantee or legal advice. Not affiliated with Anthropic, OpenAI, Cursor, GitHub or Google; product names belong to their owners. <a href="../handbook/07-security-privacy-legal.html">Legal details</a>.</p>
70
70
  </div>
71
71
  </footer>
package/docs/handbook/06-cli-reference.md CHANGED
@@ -23,7 +23,14 @@ archsutra <command> [path] [options]
23
23
  | `uninstall` | yes | no | Remove files this tool installed |
24
24
  | `hosts` | no | no | List adapters and support levels |
25
25
  | `version` | no | no | Print version |
26
- | `design`, `review`, `threat-model`, `modernize`, `compare`, `cost`, `drift` | no | **yes** | Exit 3 and point to the skill. No API call is made |
26
+ | `review [path]` | with `--output` | no | Evidence review starter. Same findings as `audit`. `--fail-on` works |
27
+ | `design [path]` | with `--output` | no | Design starter from the module map. Decisions stay `unknown` |
28
+ | `threat-model [path]` | with `--output` | no | Security findings as observed rows. STRIDE completion stays `unknown` |
29
+ | `modernize [path]` | with `--output` | no | One slice per finding. Target architecture stays `unknown` |
30
+ | `cost [path]` | with `--output` | no | States that cost is not assessed |
31
+ | `drift` | with `--output` | no | Diff two `findings.json` files, or a project against `--baseline` |
32
+ | `compare` | with `--output` | no | Same diff as `drift`. Does not run Semgrep |
33
+ | `mcp` | no | no | MCP server on stdio. Tools: `archsutra_audit`, `archsutra_map`, `archsutra_drift` |
27
34
 
28
35
  ## Options
29
36
 
@@ -48,7 +55,7 @@ archsutra <command> [path] [options]
48
55
  | 0 | ok | success |
49
56
  | 1 | findings | `--fail-on` threshold met, install blocked by conflict, or `doctor` found a problem |
50
57
  | 2 | usage | unknown command, missing `--host`, invalid `--fail-on`, `--output` escaping the project |
51
- | 3 | needs model | a model-dependent command was invoked in the CLI |
58
+ | 3 | reserved | no current command returns 3. Starter commands write evidence and mark the rest `unknown` |
52
59
  | 4 | verify failed | at least one `verify` check failed |
53
60
  | 5 | error | unexpected internal error |
54
61
 
package/docs/handbook/07-security-privacy-legal.html CHANGED
@@ -19,7 +19,7 @@
19
19
  <link rel="icon" href="../assets/favicon.svg" type="image/svg+xml">
20
20
  <link rel="stylesheet" href="../assets/site.css">
21
21
  <script>try{var t=localStorage.getItem('as-theme');if(t)document.documentElement.setAttribute('data-theme',t)}catch(e){}</script>
22
- <script type="application/ld+json">{"@context":"https://schema.org","@type":"TechArticle","headline":"Security, privacy and legal","description":"Security model, privacy guarantees, license, trademarks, disclaimers, and what has not been checked.","author":{"@type":"Person","name":"Vatsal Shah"},"inLanguage":"en","isPartOf":{"@type":"WebSite","name":"ArchSutra AI","url":"https://shahvatsalofficial.github.io/archsutra-ai"}}</script>
22
+ <script type="application/ld+json">{"@context":"https://schema.org","@type":"TechArticle","headline":"Security, privacy and legal","description":"Security model, privacy guarantees, license, trademarks, disclaimers, and what has not been checked.","author":{"@type":"Person","name":"Vatsal Shah","url":"https://shahvatsal.com"},"inLanguage":"en","isPartOf":{"@type":"WebSite","name":"ArchSutra AI","url":"https://shahvatsalofficial.github.io/archsutra-ai"}}</script>
23
23
  </head>
24
24
  <body class="doc">
25
25
  <a class="skip" href="#main">Skip to content</a>
@@ -34,7 +34,7 @@
34
34
  <div class="layout">
35
35
  <aside id="sidebar" class="sidebar" aria-label="Documentation"><div class="nav-group"><p class="nav-title">Handbook</p><ul><li><a href="../handbook/index.html">Overview</a></li><li><a href="../handbook/01-executive-summary.html">Executive summary</a></li><li><a href="../handbook/02-functional-specification.html">Functional specification</a></li><li><a href="../handbook/03-technical-specification.html">Technical specification</a></li><li><a href="../handbook/04-architecture.html">Architecture</a></li><li><a href="../handbook/05-user-guide.html">User guide</a></li><li><a href="../handbook/06-cli-reference.html">CLI reference</a></li><li><a href="../handbook/07-security-privacy-legal.html" aria-current="page">Security, privacy and legal</a></li><li><a href="../handbook/08-testing-and-proof.html">Testing and proof</a></li><li><a href="../handbook/09-compatibility-and-roadmap.html">Compatibility and roadmap</a></li><li><a href="../handbook/10-contributor-guide.html">Contributor guide</a></li><li><a href="../handbook/11-glossary-and-faq.html">Glossary and FAQ</a></li><li><a href="../handbook/12-rule-catalog.html">Audit rule catalog</a></li><li><a href="../handbook/13-trust-and-assurance.html">Trust and assurance</a></li><li><a href="../handbook/14-real-world-evaluation.html">Real-world evaluation</a></li><li><a href="../handbook/15-supply-chain-and-release.html">Supply chain and release</a></li><li><a href="../handbook/16-performance-and-quality-metrics.html">Performance and quality metrics</a></li></ul></div><div class="nav-group"><p class="nav-title">Reference</p><ul><li><a href="../architecture/overview.html">Architecture overview</a></li><li><a href="../architecture/threat-model.html">Threat model (ArchSutra CLI and skills)</a></li><li><a href="../compatibility/matrix.html">Compatibility matrix</a></li><li><a href="../rfc/0001-archsutra-v0.1.html">RFC 0001: ArchSutra AI v0.1</a></li><li><a href="../decisions/ADR-0001-deterministic-cli-plus-ide-skills.html">ADR-0001: Deterministic CLI plus IDE-native skills</a></li><li><a href="../compatibility/smoke-tests/index.html">Live smoke tests</a></li><li><a href="../community/good-first-issues.html">Good first issues (ready to file)</a></li><li><a href="../legal/trademark-and-name-clearance.html">Name and trademark clearance</a></li><li><a href="../legal/legal-review-brief.html">Legal review brief</a></li><li><a href="../proof/accessibility.html">Accessibility audit of the documentation site</a></li></ul></div></aside>
36
36
  <main id="main" class="content"><article class="prose"><p class="crumbs"><a href="../index.html">ArchSutra AI</a> / Handbook</p><h1 id="security-privacy-and-legal">Security, privacy and legal</h1>
37
- <p class="lede">Security model, privacy guarantees, license, trademarks, disclaimers, and what has not been checked.</p><p class="meta">Version 0.1.2 &middot; Source: <a href="https://github.com/shahvatsalofficial/archsutra-ai/blob/main/docs/handbook/07-security-privacy-legal.md" rel="noopener">docs/handbook/07-security-privacy-legal.md</a></p>
37
+ <p class="lede">Security model, privacy guarantees, license, trademarks, disclaimers, and what has not been checked.</p><p class="meta">Version 0.1.4 &middot; Source: <a href="https://github.com/shahvatsalofficial/archsutra-ai/blob/main/docs/handbook/07-security-privacy-legal.md" rel="noopener">docs/handbook/07-security-privacy-legal.md</a></p>
38
38
  <blockquote>This document describes the project's design and intentions. It is <strong>not legal advice</strong>. For decisions with legal effect, consult a qualified lawyer.</blockquote>
39
39
  <h2 id="1-security-model">1. Security model<a class="anchor" href="#1-security-model" aria-label="Link to this section">#</a></h2>
40
40
  <div class="table-wrap" tabindex="0" role="region" aria-label="Table 1: 1. Security model"><table><thead><tr><th scope="col">Principle</th><th scope="col">Implementation</th></tr></thead><tbody><tr><td>Read-only by default</td><td><code>audit</code>, <code>map</code>, <code>verify</code>, <code>doctor</code>, <code>init</code>, <code>hosts</code> never write. Writes happen only in <code>export</code>, <code>install</code>, <code>uninstall</code></td></tr><tr><td>Containment</td><td>all writes use <code>safeJoin</code>; <code>--output</code> that escapes the project is rejected</td></tr><tr><td>No symlink following</td><td><code>walk</code> skips symlinks; installer skips symlinks in canonical content</td></tr><tr><td>Bounded work</td><td>5000 files, 512 KiB per file, 15 s; truncation is reported</td></tr><tr><td>Secret redaction</td><td>values never appear in reports or JSON; <code>.env</code> contents are not read into reports</td></tr><tr><td>No code execution</td><td>the CLI never executes code from the scanned repository</td></tr><tr><td>Reversible changes</td><td>install manifest with SHA-256; backups; uninstall keeps user-edited files</td></tr><tr><td>Least privilege agents</td><td>Claude agent profiles get <code>Read, Grep, Glob</code> only; Copilot agents <code>read</code>, <code>search</code></td></tr><tr><td>Supply chain</td><td>zero runtime dependencies; Dependabot; CodeQL; CI blocks non-empty production dependencies</td></tr><tr><td>Prompt-injection stance</td><td>skills declare repository content as untrusted data; agents are read-only by default</td></tr></tbody></table></div>
@@ -48,7 +48,7 @@
48
48
  <h2 id="3-licensing">3. Licensing<a class="anchor" href="#3-licensing" aria-label="Link to this section">#</a></h2>
49
49
  <ul><li>Project license: <strong>Apache License 2.0</strong> (<a href="https://github.com/shahvatsalofficial/archsutra-ai/blob/main/LICENSE" rel="noopener">LICENSE</a>). Permits commercial use, modification, distribution, and patent use, with attribution, notice retention, and no trademark grant.</li><li><a href="https://github.com/shahvatsalofficial/archsutra-ai/blob/main/NOTICE" rel="noopener">NOTICE</a> must be retained in redistributions.</li><li>No runtime dependencies. Dev dependencies: TypeScript (Apache-2.0), @types/node (MIT). Details: <a href="https://github.com/shahvatsalofficial/archsutra-ai/blob/main/THIRD_PARTY_NOTICES.md" rel="noopener">THIRD_PARTY_NOTICES</a>.</li><li>Contributions: under Apache-2.0 section 5 (inbound = outbound), unless stated otherwise.</li><li>Referenced standards (OWASP, C4, SARIF, Mermaid, STRIDE, Agent Skills) are cited by name and link; no text is copied.</li><li>Original content: the skills, agents, rules and documentation are original work by the creator and contributors.</li></ul>
50
50
  <h2 id="4-names-trademarks-and-affiliations">4. Names, trademarks and affiliations<a class="anchor" href="#4-names-trademarks-and-affiliations" aria-label="Link to this section">#</a></h2>
51
- <ul><li>&quot;ArchSutra&quot;, &quot;ArchSutra AI&quot; and &quot;ArchSutra Prime&quot; are used by this project. <strong>No trademark search or registration has been performed.</strong> On 2026-10-31 the npm names <code>archsutra</code> and <code>archsutra-ai</code> were unclaimed and GitHub search found no other repository named <code>archsutra</code>; web searches on 2026-11-01 found no product, company or trademark record with the name. Details and limits: <a href="../legal/trademark-and-name-clearance.html">name clearance</a>. That is a spot check, not legal clearance. Do a proper search before any commercial launch, paid product or registration.</li><li>Third-party names (Claude, Claude Code, Anthropic, Cursor, OpenAI, Codex, GitHub, GitHub Copilot, Google, Gemini, Node.js, npm, OWASP, Mermaid) belong to their owners. They appear only to describe compatibility (nominative use). This project is <strong>not affiliated with, endorsed by, or sponsored by</strong> any of them.</li></ul>
51
+ <ul><li>&quot;ArchSutra&quot;, &quot;ArchSutra AI&quot; and &quot;ArchSutra Prime&quot; are used by this project. <strong>No trademark search or registration has been performed.</strong> On 2026-10-31 the npm names <code>archsutra</code> and <code>archsutra-ai</code> were unclaimed and GitHub search found no other repository named <code>archsutra</code>; web searches on 2026-11-01 found no product, company or trademark record with the name. On 2026-11-06 <code>archsutra-ai</code> is this project's published npm package and <code>archsutra</code> was still unclaimed. Details and limits: <a href="../legal/trademark-and-name-clearance.html">name clearance</a>. That is a spot check, not legal clearance. Do a proper search before any commercial launch, paid product or registration.</li><li>Third-party names (Claude, Claude Code, Anthropic, Cursor, OpenAI, Codex, GitHub, GitHub Copilot, Google, Gemini, Node.js, npm, OWASP, Mermaid) belong to their owners. They appear only to describe compatibility (nominative use). This project is <strong>not affiliated with, endorsed by, or sponsored by</strong> any of them.</li></ul>
52
52
  <h2 id="5-disclaimers">5. Disclaimers<a class="anchor" href="#5-disclaimers" aria-label="Link to this section">#</a></h2>
53
53
  <ul><li><strong>No warranty.</strong> Provided &quot;AS IS&quot; (Apache-2.0 sections 7 and 8).</li><li><strong>No compliance claim.</strong> Reports are review aids. They do not certify conformance with any law, regulation or standard (including GDPR, HIPAA, PCI DSS, SOC 2, ISO 27001, NIST, OWASP). Mentions of frameworks are references for human reviewers.</li><li><strong>No security guarantee.</strong> Absence of findings does not mean absence of vulnerabilities. Do not rely on this tool as the sole control.</li><li><strong>Authorized use only.</strong> Run the tool only on code you own or are authorized to review. The CLI does not scan networks or run exploits.</li><li><strong>AI output.</strong> Skill-driven results come from third-party models and can be wrong. Verify before acting; the skills instruct the model to cite evidence so you can.</li></ul>
54
54
  <h2 id="6-open-legal-and-compliance-checks-not-done">6. Open legal and compliance checks (not done)<a class="anchor" href="#6-open-legal-and-compliance-checks-not-done" aria-label="Link to this section">#</a></h2>
@@ -57,7 +57,7 @@
57
57
  </div>
58
58
  <footer class="footer">
59
59
  <div class="footer-inner">
60
- <p><strong>ArchSutra AI</strong> v0.1.2. Design. Audit. Evolve. Created by <a href="https://github.com/shahvatsalofficial" rel="noopener">Vatsal Shah</a>. Licensed under <a href="https://github.com/shahvatsalofficial/archsutra-ai/blob/main/LICENSE" rel="noopener">Apache-2.0</a>.</p>
60
+ <p><strong>ArchSutra AI</strong> v0.1.4. Design. Audit. Evolve. Created by <a href="https://shahvatsal.com" rel="noopener">Vatsal Shah</a>. Licensed under <a href="https://github.com/shahvatsalofficial/archsutra-ai/blob/main/LICENSE" rel="noopener">Apache-2.0</a>.</p>
61
61
  <p class="fine">Review aid only. Not a certification, compliance attestation, security guarantee or legal advice. Not affiliated with Anthropic, OpenAI, Cursor, GitHub or Google; product names belong to their owners. <a href="../handbook/07-security-privacy-legal.html">Legal details</a>.</p>
62
62
  </div>
63
63
  </footer>
package/docs/handbook/07-security-privacy-legal.md CHANGED
@@ -49,7 +49,7 @@ Use GitHub private vulnerability reporting: https://github.com/shahvatsalofficia
49
49
 
50
50
  ## 4. Names, trademarks and affiliations
51
51
 
52
- - "ArchSutra", "ArchSutra AI" and "ArchSutra Prime" are used by this project. **No trademark search or registration has been performed.** On 2026-10-31 the npm names `archsutra` and `archsutra-ai` were unclaimed and GitHub search found no other repository named `archsutra`; web searches on 2026-11-01 found no product, company or trademark record with the name. Details and limits: [name clearance](../legal/trademark-and-name-clearance.md). That is a spot check, not legal clearance. Do a proper search before any commercial launch, paid product or registration.
52
+ - "ArchSutra", "ArchSutra AI" and "ArchSutra Prime" are used by this project. **No trademark search or registration has been performed.** On 2026-10-31 the npm names `archsutra` and `archsutra-ai` were unclaimed and GitHub search found no other repository named `archsutra`; web searches on 2026-11-01 found no product, company or trademark record with the name. On 2026-11-06 `archsutra-ai` is this project's published npm package and `archsutra` was still unclaimed. Details and limits: [name clearance](../legal/trademark-and-name-clearance.md). That is a spot check, not legal clearance. Do a proper search before any commercial launch, paid product or registration.
53
53
  - Third-party names (Claude, Claude Code, Anthropic, Cursor, OpenAI, Codex, GitHub, GitHub Copilot, Google, Gemini, Node.js, npm, OWASP, Mermaid) belong to their owners. They appear only to describe compatibility (nominative use). This project is **not affiliated with, endorsed by, or sponsored by** any of them.
54
54
 
55
55
  ## 5. Disclaimers