arcshape 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "arcshape",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "ArcShape tooling for creating and maintaining arc42 architecture documentation.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/juangcarmona/arcshape.git"
+  },
+  "homepage": "https://github.com/juangcarmona/arcshape#readme",
+  "bugs": {
+    "url": "https://github.com/juangcarmona/arcshape/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "arcshape": "bin/arcshape.mjs"
+  },
+  "files": [
+    "bin/",
+    "tools/arc42-site/",
+    "templates/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "@mermaid-js/mermaid-cli": "12.0.0",
+    "dompurify": "3.4.16",
+    "github-slugger": "2.0.0",
+    "ignore": "7.0.12",
+    "js-yaml": "5.4.3",
+    "jsdom": "27.4.0",
+    "marked": "15.0.12",
+    "puppeteer": "25.12.0",
+    "yauzl": "3.4.0"
+  },
+  "scripts": {
+    "format:check": "prettier --check \"bin/**/*.{js,mjs}\" \"tools/arc42-site/**/*.mjs\" \"scripts/**/*.{ts,js,mjs}\" \"tests/**/*.{ts,js,mjs}\" \"security/**/*.json\" \"*.js\" \"*.json\" \".github/workflows/*.yml\"",
+    "lint": "eslint bin scripts tests eslint.config.js",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "build": "tsc",
+    "product:model:check": "node dist/scripts/check-product-model-status.js docs/product/model",
+    "security:audit": "node scripts/check-npm-audit.mjs",
+    "openspec:init": "openspec init --tools codex,claude",
+    "product:init": "prodshape init --sdd openspec --ai codex,claude --full",
+    "product:openspec:add": "prodshape integration add openspec"
+  },
+  "devDependencies": {
+    "@fission-ai/openspec": "1.14.2",
+    "@prodshape/cli": "0.22.0",
+    "@types/node": "24.13.3",
+    "eslint": "10.13.0",
+    "prettier": "3.9.6",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.65.0",
+    "vitest": "5.0.5"
+  }
+}

package/templates/architecture/01-introduction-and-goals.md

@@ -0,0 +1,13 @@
+---
+title: Introduction and goals
+arc42-section: "01"
+description: System purpose, stakeholders, and architecture goals.
+---
+
+# 1. Introduction and goals
+
+## Requirements overview
+
+## Quality goals
+
+## Stakeholders

package/templates/architecture/02-constraints.md

@@ -0,0 +1,13 @@
+---
+title: Architecture constraints
+arc42-section: "02"
+description: Technical, organizational, and convention constraints that shape the architecture.
+---
+
+# 2. Architecture constraints
+
+## Technical constraints
+
+## Organizational constraints
+
+## Conventions

package/templates/architecture/03-context-and-scope.md

@@ -0,0 +1,11 @@
+---
+title: System scope and context
+arc42-section: "03"
+description: The system boundary, its users, and its external interfaces.
+---
+
+# 3. System scope and context
+
+## Business context
+
+## Technical context

package/templates/architecture/04-solution-strategy.md

@@ -0,0 +1,13 @@
+---
+title: Solution strategy
+arc42-section: "04"
+description: Fundamental decisions and strategies that shape the architecture.
+---
+
+# 4. Solution strategy
+
+## Technology decisions
+
+## Top-level decomposition
+
+## Quality realization

package/templates/architecture/05-building-block-view.md

@@ -0,0 +1,11 @@
+---
+title: Building block view
+arc42-section: "05"
+description: The static decomposition of the system into building blocks.
+---
+
+# 5. Building block view
+
+## Level 1: system
+
+## Level 2: building blocks

package/templates/architecture/06-runtime-view.md

@@ -0,0 +1,9 @@
+---
+title: Runtime view
+arc42-section: "06"
+description: Runtime behavior and important interactions between building blocks.
+---
+
+# 6. Runtime view
+
+## Runtime scenarios

package/templates/architecture/07-deployment-view.md

@@ -0,0 +1,11 @@
+---
+title: Deployment view
+arc42-section: "07"
+description: Infrastructure and environment mapping for the system.
+---
+
+# 7. Deployment view
+
+## Infrastructure overview
+
+## Deployment mapping

package/templates/architecture/08-crosscutting-concepts.md

@@ -0,0 +1,13 @@
+---
+title: Cross-cutting concepts
+arc42-section: "08"
+description: Concepts and rules that affect multiple building blocks.
+---
+
+# 8. Cross-cutting concepts
+
+## Domain model
+
+## Security and privacy
+
+## Observability and operations

package/templates/architecture/09-architecture-decisions.md

@@ -0,0 +1,9 @@
+---
+title: Architecture decisions
+arc42-section: "09"
+description: Important architecture decisions and links to their records.
+---
+
+# 9. Architecture decisions
+
+Link the accepted Architecture Decision Records that explain consequential choices.

package/templates/architecture/10-quality-requirements.md

@@ -0,0 +1,11 @@
+---
+title: Quality requirements
+arc42-section: "10"
+description: Quality goals and concrete scenarios for evaluating them.
+---
+
+# 10. Quality requirements
+
+## Quality tree
+
+## Quality scenarios

package/templates/architecture/11-risks-and-technical-debt.md

@@ -0,0 +1,11 @@
+---
+title: Risks and technical debt
+arc42-section: "11"
+description: Known risks, technical debt, and their planned responses.
+---
+
+# 11. Risks and technical debt
+
+## Risks
+
+## Technical debt

package/templates/architecture/12-glossary.md

@@ -0,0 +1,10 @@
+---
+title: Glossary
+arc42-section: "12"
+description: Domain and architecture terminology used in this documentation.
+---
+
+# 12. Glossary
+
+| Term | Definition |
+| ---- | ---------- |

package/templates/architecture/README.md

@@ -0,0 +1,20 @@
+# Architecture documentation
+
+This directory contains the system's canonical architecture documentation in Markdown. It follows the twelve sections of [arc42](https://arc42.org/).
+
+## Sections
+
+1. [Introduction and goals](01-introduction-and-goals.md)
+2. [Architecture constraints](02-constraints.md)
+3. [System scope and context](03-context-and-scope.md)
+4. [Solution strategy](04-solution-strategy.md)
+5. [Building block view](05-building-block-view.md)
+6. [Runtime view](06-runtime-view.md)
+7. [Deployment view](07-deployment-view.md)
+8. [Cross-cutting concepts](08-crosscutting-concepts.md)
+9. [Architecture decisions](09-architecture-decisions.md)
+10. [Quality requirements](10-quality-requirements.md)
+11. [Risks and technical debt](11-risks-and-technical-debt.md)
+12. [Glossary](12-glossary.md)
+
+Keep Markdown as the source of truth. Separate known implementation evidence from assumptions and open questions; do not treat an inferred decision as accepted.

package/templates/assistants/.agents/skills/arcshape-adr/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: arcshape-adr
+description: Draft, review, and maintain Markdown Architecture Decision Records from a decision supplied by a maintainer and supporting repository evidence. Use when a durable architecture trade-off needs a record.
+---
+
+# ArcShape ADR workflow
+
+1. Confirm the decision being made and who has authority to accept it. If the decision itself is unknown, ask; do not infer a choice from implementation alone.
+2. Inspect existing ADR conventions, indexes, relevant arc42 sections, and evidence. Default only when no repository convention exists: `docs/adr/` with four-digit sequential filenames.
+3. Draft a Markdown ADR with Context, Decision, Alternatives considered, Consequences, and References. Separate supplied decisions from observed facts and unresolved assumptions.
+4. New records are Proposed unless the maintainer explicitly says the decision is accepted. Include the rejected alternatives and why they were rejected.
+5. Never rewrite history to reverse a decision. Propose a new ADR and show any superseding relationship for review. Keep the existing ADR's status until the new decision is accepted; then mark the old record superseded. Confirm the relationship with the maintainer before recording it.
+6. Update an existing ADR index if the repository has one. For an accepted decision, update arc42 section 09 when present with a concise decision, ADR link, and affected architecture. Do not put proposed decisions in the current architecture index.
+7. Show the complete diff and summarize open questions. Leave acceptance to the maintainer.
+
+Keep the ADR and its index in Markdown. Do not invent a repository index if the project has none; report that clearly.

package/templates/assistants/.agents/skills/arcshape-architecture/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: arcshape-architecture
+description: Reverse engineer, create, and maintain evidence-grounded arc42 architecture documentation in Markdown for any repository. Use when documenting a system, improving architecture docs, or reconciling docs with implementation evidence.
+---
+
+# ArcShape architecture documentation
+
+Use this skill to understand a repository and propose accurate architecture documentation. The repository language and stack are not prerequisites: follow evidence in Markdown, configuration, source, tests, deployment manifests, and operational files.
+
+## Operating rules
+
+- Treat existing repository evidence as observations, not proof of intent. Distinguish observed behavior, maintainer-supplied intent, and proposals.
+- Never claim a subsystem or behavior is implemented based only on plans, issue text, or generated docs. Cite concrete paths and relevant sections in the working notes.
+- Surface contradictions, gaps, uncertainty, and stale documentation. Ask the maintainer when a decision or intent cannot be inferred safely.
+- Preserve the project's existing architecture documentation conventions. ArcShape's default Markdown location is `docs/architecture/` with the 12 numbered arc42 sections.
+- Draft changes for review. Do not declare proposals accepted or silently overwrite a maintainer's authored material.
+- Keep diagrams in Mermaid inside Markdown. Prefer C4 context/container/component views and label relationships with concise meaning.
+
+## Reverse engineering workflow
+
+1. Inspect repository guidance, existing architecture docs, ADRs, product definition, and recent changes before analyzing implementation.
+2. Start or resume a bounded evidence session with `arcshape session start` / `arcshape session status` / `arcshape session next`. Use each returned round to inspect sources; do not attempt to read the entire repository in one pass.
+3. For each source, record its classification and what it establishes with `arcshape session mark`. Record newly discovered paths as leads and unresolved intent as questions. Correct mistakes with `unmark`; preserve uncertainty instead of filling gaps.
+4. Track coverage and changed evidence. Re-read sources ArcShape reports as changed before relying on earlier notes. Continue until the session report distinguishes reviewed, excluded, pending, and changed evidence.
+5. Build a compact evidence map: system boundary, users/external systems, runtime units, interfaces, data stores, deployment, cross-cutting mechanisms, quality goals, risks, and unknowns. Link every material claim to evidence.
+6. Compare the evidence map with the 12 arc42 sections. Propose focused Markdown edits, marking inferred claims and unresolved questions for maintainer review.
+7. Review all internal links and Mermaid syntax, then build the reader site with `arcshape site build` and inspect the generated output.
+
+## Maintain documentation
+
+When docs already exist, compare each claim against current evidence. Preserve accurate content, correct stale details, remove duplication, and record unresolved discrepancies. Do not rewrite sections merely to fit a template. Keep source Markdown canonical; the HTML site is generated output.
+
+## CLI tools
+
+Use the CLI for repeatable operations: `arcshape init`, `arcshape session ...`, `arcshape validate`, `arcshape sync ...`, and `arcshape site build`. Run `arcshape validate --links --citations` when the repository has a ProductShape model. Citation validation uses the repository's installed `@prodshape/cli`; it reports stale citations as warnings and unresolved citations as errors. Do not rewrite citations automatically. This skill owns repository interpretation, questions, and proposed documentation. Report when a requested deterministic CLI subcommand is unavailable; do not invent one.

package/templates/assistants/.agents/skills/arcshape-c4/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: arcshape-c4
+description: Create and maintain evidence-grounded C4 architecture diagrams as Mermaid in Markdown. Use when a maintainer asks for context, container, component, or code views.
+---
+
+# ArcShape C4 diagram workflow
+
+1. Inspect current documentation, repository structure, runtime configuration, deployment, interfaces, and tests. Ask the maintainer about external actors or intended boundaries that evidence cannot establish.
+2. Choose the smallest useful C4 level: context, container, component, or code. Do not produce every level by default.
+3. Draft Mermaid `C4Context`, `C4Container`, or `C4Component` diagrams in the appropriate Markdown arc42 section. Keep names and relationship labels concise.
+4. Ground nodes and relationships in evidence. Mark inferred boundaries and unknown relationships for review; do not imply that a planned component exists.
+5. Preserve existing correct diagrams and propose focused edits. When evidence changes, update only affected nodes, relationships, and adjacent explanation; leave unrelated authored content unchanged and show the diff. Do not overwrite diagrams from external sources without review.
+6. Run `arcshape site build` and inspect the rendered diagram. Report Mermaid render failures and unresolved assumptions.

package/templates/assistants/.agents/skills/arcshape-docs-sync/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: arcshape-docs-sync
+description: Connect repository architecture Markdown to Obsidian or Confluence while keeping the repository copy reviewable and canonical. Use when a maintainer asks to link, export, or publish architecture documentation.
+---
+
+# ArcShape documentation connections
+
+1. Confirm the source Markdown directory and the target vault or documentation space with the maintainer. Treat repository Markdown as canonical unless the maintainer explicitly describes another source of truth.
+2. For an Obsidian vault, preview with `arcshape sync obsidian --vault <vault> --include <ADR-directory> --dry-run` when ADRs live outside `docs/architecture`. The selected Markdown roots are copied with their relative structure so links between architecture docs and ADRs remain usable. Review target and file actions, then run without `--dry-run` when the maintainer has asked to sync. ArcShape updates only copies that still match its prior managed version; conflicts preserve vault edits for human reconciliation.
+3. For Confluence Cloud, preview a multi-page architecture publication with `arcshape sync confluence --base-url <url> --space-id <id> --parent-id <id> --title-prefix <project> --dry-run`. This creates an index and one page per arc42 section under the selected parent. Add repeatable `--include <file-or-directory>` options for selected ADR or C4 Markdown outside `docs/architecture`. For an existing single-page destination, use `--page-id <id>` instead. Credentials must be supplied in environment variables; never put tokens in repository files or command arguments. The CLI stops when a managed remote page changed since the last sync. Remove `--dry-run` only when the maintainer has asked to publish that content.
+4. Never copy credentials into repository files, include private content outside the requested scope, or silently overwrite an externally edited document.
+5. Report which files/pages were linked, created, updated, unchanged, or conflicted. Keep canonical Markdown and external-system references traceable.

package/templates/assistants/.claude/commands/arcshape/adr.md

@@ -0,0 +1,5 @@
+# /arcshape:adr
+
+Draft or maintain a Markdown Architecture Decision Record.
+
+Use the `arcshape-adr` skill. Ask for the decision when it is not supplied; distinguish maintainer decisions from facts inferred from repository evidence. Keep the ADR Proposed unless acceptance is explicit, preserve history, update an existing index, and present the diff for review.

package/templates/assistants/.claude/commands/arcshape/c4.md

@@ -0,0 +1,5 @@
+# /arcshape:c4
+
+Create or update an evidence-grounded C4 diagram in Markdown.
+
+Use the `arcshape-c4` skill. Select the smallest useful C4 level, use Mermaid, ground nodes and relationships in repository evidence, call out unknown boundaries, then build and inspect the site. Present the diff for review.

package/templates/assistants/.claude/commands/arcshape/document.md

@@ -0,0 +1,5 @@
+# /arcshape:document
+
+Create or improve this repository's arc42 architecture documentation in Markdown.
+
+Use the `arcshape-architecture` skill. Review existing docs and implementation evidence, update only supported claims, surface gaps, and build the reader site with `arcshape site build` for review. Preserve source Markdown as canonical and show the proposed diff.

package/templates/assistants/.claude/commands/arcshape/reverse-engineer.md

@@ -0,0 +1,5 @@
+# /arcshape:reverse-engineer
+
+Reverse engineer this repository's architecture and prepare evidence-grounded Markdown documentation.
+
+Use the `arcshape-architecture` skill. Start or resume a bounded session with `arcshape session`, inspect one round at a time, record coverage and unresolved questions, then propose focused edits to `docs/architecture/`. Keep observed behavior separate from plans and maintainer intent. Do not accept changes on the maintainer's behalf.

package/templates/assistants/.claude/commands/arcshape/sync.md

@@ -0,0 +1,5 @@
+# /arcshape:sync
+
+Connect this repository's architecture Markdown to the documentation system used by the project.
+
+Use the `arcshape-docs-sync` skill. It documents ArcShape's native Obsidian and Confluence CLI commands, preview options, credential handling, and conflict behavior. Prepare a reviewable preview and publish only after the maintainer asks.

package/templates/assistants/.claude/skills/arcshape-adr/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: arcshape-adr
+description: Draft, review, and maintain Markdown Architecture Decision Records from a decision supplied by a maintainer and supporting repository evidence. Use when a durable architecture trade-off needs a record.
+---
+
+# ArcShape ADR workflow
+
+1. Confirm the decision being made and who has authority to accept it. If the decision itself is unknown, ask; do not infer a choice from implementation alone.
+2. Inspect existing ADR conventions, indexes, relevant arc42 sections, and evidence. Default only when no repository convention exists: `docs/adr/` with four-digit sequential filenames.
+3. Draft a Markdown ADR with Context, Decision, Alternatives considered, Consequences, and References. Separate supplied decisions from observed facts and unresolved assumptions.
+4. New records are Proposed unless the maintainer explicitly says the decision is accepted. Include the rejected alternatives and why they were rejected.
+5. Never rewrite history to reverse a decision. Propose a new ADR and show any superseding relationship for review. Keep the existing ADR's status until the new decision is accepted; then mark the old record superseded. Confirm the relationship with the maintainer before recording it.
+6. Update an existing ADR index if the repository has one. For an accepted decision, update arc42 section 09 when present with a concise decision, ADR link, and affected architecture. Do not put proposed decisions in the current architecture index.
+7. Show the complete diff and summarize open questions. Leave acceptance to the maintainer.
+
+Keep the ADR and its index in Markdown. Do not invent a repository index if the project has none; report that clearly.

package/templates/assistants/.claude/skills/arcshape-architecture/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: arcshape-architecture
+description: Reverse engineer, create, and maintain evidence-grounded arc42 architecture documentation in Markdown for any repository. Use when documenting a system, improving architecture docs, or reconciling docs with implementation evidence.
+---
+
+# ArcShape architecture documentation
+
+Use this skill to understand a repository and propose accurate architecture documentation. The repository language and stack are not prerequisites: follow evidence in Markdown, configuration, source, tests, deployment manifests, and operational files.
+
+## Operating rules
+
+- Treat existing repository evidence as observations, not proof of intent. Distinguish observed behavior, maintainer-supplied intent, and proposals.
+- Never claim a subsystem or behavior is implemented based only on plans, issue text, or generated docs. Cite concrete paths and relevant sections in the working notes.
+- Surface contradictions, gaps, uncertainty, and stale documentation. Ask the maintainer when a decision or intent cannot be inferred safely.
+- Preserve the project's existing architecture documentation conventions. ArcShape's default Markdown location is `docs/architecture/` with the 12 numbered arc42 sections.
+- Draft changes for review. Do not declare proposals accepted or silently overwrite a maintainer's authored material.
+- Keep diagrams in Mermaid inside Markdown. Prefer C4 context/container/component views and label relationships with concise meaning.
+
+## Reverse engineering workflow
+
+1. Inspect repository guidance, existing architecture docs, ADRs, product definition, and recent changes before analyzing implementation.
+2. Start or resume a bounded evidence session with `arcshape session start` / `arcshape session status` / `arcshape session next`. Use each returned round to inspect sources; do not attempt to read the entire repository in one pass.
+3. For each source, record its classification and what it establishes with `arcshape session mark`. Record newly discovered paths as leads and unresolved intent as questions. Correct mistakes with `unmark`; preserve uncertainty instead of filling gaps.
+4. Track coverage and changed evidence. Re-read sources ArcShape reports as changed before relying on earlier notes. Continue until the session report distinguishes reviewed, excluded, pending, and changed evidence.
+5. Build a compact evidence map: system boundary, users/external systems, runtime units, interfaces, data stores, deployment, cross-cutting mechanisms, quality goals, risks, and unknowns. Link every material claim to evidence.
+6. Compare the evidence map with the 12 arc42 sections. Propose focused Markdown edits, marking inferred claims and unresolved questions for maintainer review.
+7. Review all internal links and Mermaid syntax, then build the reader site with `arcshape site build` and inspect the generated output.
+
+## Maintain documentation
+
+When docs already exist, compare each claim against current evidence. Preserve accurate content, correct stale details, remove duplication, and record unresolved discrepancies. Do not rewrite sections merely to fit a template. Keep source Markdown canonical; the HTML site is generated output.
+
+## CLI tools
+
+Use the CLI for repeatable operations: `arcshape init`, `arcshape session ...`, `arcshape validate`, `arcshape sync ...`, and `arcshape site build`. Run `arcshape validate --links --citations` when the repository has a ProductShape model. Citation validation uses the repository's installed `@prodshape/cli`; it reports stale citations as warnings and unresolved citations as errors. Do not rewrite citations automatically. This skill owns repository interpretation, questions, and proposed documentation. Report when a requested deterministic CLI subcommand is unavailable; do not invent one.

package/templates/assistants/.claude/skills/arcshape-c4/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: arcshape-c4
+description: Create and maintain evidence-grounded C4 architecture diagrams as Mermaid in Markdown. Use when a maintainer asks for context, container, component, or code views.
+---
+
+# ArcShape C4 diagram workflow
+
+1. Inspect current documentation, repository structure, runtime configuration, deployment, interfaces, and tests. Ask the maintainer about external actors or intended boundaries that evidence cannot establish.
+2. Choose the smallest useful C4 level: context, container, component, or code. Do not produce every level by default.
+3. Draft Mermaid `C4Context`, `C4Container`, or `C4Component` diagrams in the appropriate Markdown arc42 section. Keep names and relationship labels concise.
+4. Ground nodes and relationships in evidence. Mark inferred boundaries and unknown relationships for review; do not imply that a planned component exists.
+5. Preserve existing correct diagrams and propose focused edits. When evidence changes, update only affected nodes, relationships, and adjacent explanation; leave unrelated authored content unchanged and show the diff. Do not overwrite diagrams from external sources without review.
+6. Run `arcshape site build` and inspect the rendered diagram. Report Mermaid render failures and unresolved assumptions.

package/templates/assistants/.claude/skills/arcshape-docs-sync/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: arcshape-docs-sync
+description: Connect repository architecture Markdown to Obsidian or Confluence while keeping the repository copy reviewable and canonical. Use when a maintainer asks to link, export, or publish architecture documentation.
+---
+
+# ArcShape documentation connections
+
+1. Confirm the source Markdown directory and the target vault or documentation space with the maintainer. Treat repository Markdown as canonical unless the maintainer explicitly describes another source of truth.
+2. For an Obsidian vault, preview with `arcshape sync obsidian --vault <vault> --include <ADR-directory> --dry-run` when ADRs live outside `docs/architecture`. The selected Markdown roots are copied with their relative structure so links between architecture docs and ADRs remain usable. Review target and file actions, then run without `--dry-run` when the maintainer has asked to sync. ArcShape updates only copies that still match its prior managed version; conflicts preserve vault edits for human reconciliation.
+3. For Confluence Cloud, preview a multi-page architecture publication with `arcshape sync confluence --base-url <url> --space-id <id> --parent-id <id> --title-prefix <project> --dry-run`. This creates an index and one page per arc42 section under the selected parent. Add repeatable `--include <file-or-directory>` options for selected ADR or C4 Markdown outside `docs/architecture`. For an existing single-page destination, use `--page-id <id>` instead. Credentials must be supplied in environment variables; never put tokens in repository files or command arguments. The CLI stops when a managed remote page changed since the last sync. Remove `--dry-run` only when the maintainer has asked to publish that content.
+4. Never copy credentials into repository files, include private content outside the requested scope, or silently overwrite an externally edited document.
+5. Report which files/pages were linked, created, updated, unchanged, or conflicted. Keep canonical Markdown and external-system references traceable.

package/tools/arc42-site/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Juan G. Carmona
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/tools/arc42-site/NOTICE.md

@@ -0,0 +1,3 @@
+# arc42 snapshot generator notice
+
+The generator in this directory is copied from the `architecture-docs` skill available to Raccord maintainers and is provided under the MIT License in `LICENSE`. Its runtime dependencies are pinned by `package-lock.json`; the canonical architecture content remains in `docs/architecture/arc42/`.

package/tools/arc42-site/README.md

@@ -0,0 +1,3 @@
+# ArcShape static site renderer
+
+The self-contained arc42 renderer is adapted from Raccord's `arc42-snapshot` tool and retains its MIT license and notice in this directory. It validates the Markdown section contract, sanitizes rendered HTML, and pre-renders accessible Mermaid diagrams into one navigable HTML file. ArcShape's canonical source remains `docs/architecture/*.md`.

package/tools/arc42-site/browser-options.mjs

@@ -0,0 +1,14 @@
+export function getPuppeteerLaunchOptions(environment = process.env) {
+  return {
+    args:
+      environment.GITHUB_ACTIONS === "true"
+        ? [
+            "--no-sandbox",
+            "--disable-setuid-sandbox",
+            "--disable-dev-shm-usage",
+            "--disable-crash-reporter",
+            "--disable-breakpad",
+          ]
+        : [],
+  };
+}

package/tools/arc42-site/capture-evidence.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+
+import { mkdir } from "node:fs/promises";
+import { resolve, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import puppeteer from "puppeteer";
+import { getPuppeteerLaunchOptions } from "./browser-options.mjs";
+
+const [siteArgument, outputArgument] = process.argv.slice(2);
+if (!siteArgument || !outputArgument) {
+  process.stderr.write(
+    "Usage: node capture-evidence.mjs <site.html> <output-directory>\n",
+  );
+  process.exit(2);
+}
+
+const site = resolve(siteArgument);
+const output = resolve(outputArgument);
+await mkdir(output, { recursive: true });
+const browser = await puppeteer.launch({
+  headless: true,
+  ...getPuppeteerLaunchOptions(),
+});
+
+try {
+  const page = await browser.newPage();
+  await page.setViewport({ width: 1440, height: 1000, deviceScaleFactor: 1 });
+  const siteUrl = pathToFileURL(site).href;
+  await page.goto(`${siteUrl}#/`, { waitUntil: "load" });
+  await page.waitForSelector("#content .overview-intro");
+  await page.screenshot({ path: join(output, "arcshape-overview.png") });
+
+  await page.goto(`${siteUrl}#/section/03`, { waitUntil: "load" });
+  await page.waitForFunction(
+    () =>
+      location.hash === "#/section/03" &&
+      document.querySelector(".doc figure.diagram svg"),
+  );
+  await page.evaluate(() => {
+    const main = document.querySelector("main#main");
+    const diagram = document.querySelector(".doc figure.diagram");
+    if (main && diagram) {
+      main.style.scrollBehavior = "auto";
+      const mainBounds = main.getBoundingClientRect();
+      const diagramBounds = diagram.getBoundingClientRect();
+      main.scrollTop = Math.max(
+        0,
+        main.scrollTop +
+          diagramBounds.top -
+          mainBounds.top -
+          (main.clientHeight - diagramBounds.height) / 2,
+      );
+    }
+  });
+  await page.screenshot({ path: join(output, "arcshape-system-context.png") });
+
+  await page.goto(`${siteUrl}#/section/05`, { waitUntil: "load" });
+  await page.waitForFunction(
+    () =>
+      location.hash === "#/section/05" &&
+      document.querySelector(".doc figure.diagram svg"),
+  );
+  await page.evaluate(() => {
+    const main = document.querySelector("main#main");
+    const diagram = document.querySelector(".doc figure.diagram");
+    if (main && diagram) {
+      main.style.scrollBehavior = "auto";
+      const mainBounds = main.getBoundingClientRect();
+      const diagramBounds = diagram.getBoundingClientRect();
+      main.scrollTop = Math.max(
+        0,
+        main.scrollTop +
+          diagramBounds.top -
+          mainBounds.top -
+          (main.clientHeight - diagramBounds.height) / 2,
+      );
+    }
+  });
+  await page.screenshot({
+    path: join(output, "arcshape-building-blocks.png"),
+  });
+} finally {
+  await browser.close();
+}