arckit-cli 6.1.1__py3-none-any.whl

arckit_cli-6.1.1.data/data/share/arckit/docs/guides/mcp-servers.md

@@ -0,0 +1,329 @@
+# ArcKit Plugin Setup Guide
+
+> **Guide Origin**: Official | **ArcKit Version**: [VERSION]
+
+This guide covers installing the ArcKit plugin, configuring MCP servers, and complementary plugins that enhance architecture workflows.
+
+---
+
+## Installing the ArcKit Plugin
+
+### Prerequisites
+
+- **Claude Code** v2.1.121 or later (or **Claude Cowork** desktop app)
+- **Bash** shell (for helper scripts)
+
+### Step 0: Make sure Claude Code is up to date
+
+```bash
+claude install latest
+claude --version
+```
+
+`claude install` accepts `stable`, `latest`, or a specific version (e.g. `claude install 2.1.121`). If you don't have the `claude` CLI yet, follow the [official Claude Code install guide](https://docs.claude.com/en/docs/claude-code/quickstart) first.
+
+### Optional: Long-session prompt cache (Claude Code v2.1.108+)
+
+Long ArcKit workflows -- requirements -> data-model -> components -> stories, or any chain that re-reads the same templates, principles, and project artifacts -- benefit from the 1-hour prompt cache TTL introduced in Claude Code v2.1.108. The default 5-minute TTL expires between commands when you pause to review output, file the next prompt, or step away.
+
+Set the env var before launching Claude:
+
+```bash
+export ENABLE_PROMPT_CACHING_1H=1
+claude
+```
+
+Recommended for: overnight `autoresearch` runs, multi-command workflows (`/arckit:requirements` -> `/arckit:data-model` -> `/arckit:components`), and research agents that re-read large project context. Verify cache uplift in your Anthropic billing dashboard (`cache_read_input_tokens` should grow as a fraction of input tokens).
+
+### Optional: MCP per-request timeout (Claude Code v2.1.142+)
+
+The three bundled cloud-research MCP servers (`aws-knowledge`, `microsoft-learn`, `google-developer-knowledge`) are remote HTTP servers reached from your machine. Behind corporate proxies, TLS-inspecting gateways, or slow links, individual fetches inside a single tool call can exceed Claude Code's default per-request timeout — surfacing as `MCP tool call failed: timeout` in the middle of a long `/arckit:aws-research`, `/arckit:azure-research`, or `/arckit:gcp-research` run.
+
+Claude Code v2.1.142 made `MCP_TOOL_TIMEOUT` honour the per-request fetch timeout for remote servers (previously it only governed initial connect). Raise it for cloud-research sessions on slow networks:
+
+```bash
+# 5-minute per-request timeout (default is 60s)
+export MCP_TOOL_TIMEOUT=300000
+claude
+```
+
+The value is milliseconds. Recommended for: corporate networks with TLS-inspecting proxies, VPN-tunnelled connections, and large-scope research prompts that trigger many `microsoft_docs_fetch` / `aws___read_documentation` / `get_document` calls in sequence. On a healthy direct connection the default is fine — only set this when you see timeout failures.
+
+> **Don't set a sub-second timeout.** As of Claude Code v2.1.162, a per-server `timeout` below `1000` ms is ignored (it falls back to `MCP_TOOL_TIMEOUT` or the default) rather than being floored to a 1-second watchdog that aborted every call. ArcKit ships no sub-1000 ms timeouts, so this is reassurance only — but if you hand-edit a server's `timeout`, keep it ≥ `1000`.
+
+### Step 1: Add the marketplace
+
+In Claude Code, run:
+
+```text
+/plugin marketplace add tractorjuice/arckit-claude
+```
+
+### Step 2: Install the plugin
+
+```text
+/plugin
+```
+
+Go to the **Discover** tab, find **arckit**, and install it. Or via CLI:
+
+```bash
+claude plugin install arckit@arckit-claude
+```
+
+### Step 3: Restart Claude Code
+
+The plugin loads MCP servers and hooks at startup. **A restart is required** after first installation.
+
+### Verifying installation
+
+After restart, open the plugin manager (`/plugin`) and navigate to **Installed**. You should see:
+
+- **Commands**: ArcKit slash commands
+- **Agents**: Autonomous research agents
+- **Skills**: Reference skills (Wardley, Mermaid, PlantUML, workflow, build harness)
+- **Hooks**: SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest
+
+> **Tip**: You may see 2 MCP errors about missing API keys for Google and Data Commons. These are harmless — see [Servers Requiring API Keys](#servers-requiring-api-keys) below.
+
+> **Confirm what's enabled from the CLI** (Claude Code v2.1.163+): `/plugin list --enabled` lists the active plugins. Handy because the community overlays (`arckit-uae`, `arckit-fr`, `arckit-au`, …) ship `defaultEnabled: false` — if an overlay's `/arckit:*` commands aren't showing up, it's almost always because it wasn't enabled. Use `/plugin list --disabled` to see what's installed but off.
+
+### Auto-enabling for team repos
+
+To have the plugin auto-enable for anyone who opens your repo, add `.claude/settings.json`:
+
+```json
+{
+  "extraKnownMarketplaces": {
+    "arckit-claude": {
+      "source": {
+        "source": "github",
+        "repo": "tractorjuice/arckit-claude"
+      }
+    }
+  },
+  "enabledPlugins": {
+    "arckit@arckit-claude": true
+  }
+}
+```
+
+---
+
+## MCP Servers
+
+ArcKit includes 4 bundled MCP (Model Context Protocol) servers for cloud research, plus support for optional third-party MCPs like Pinecone.
+
+> **Two servers work out of the box** (AWS Knowledge, Microsoft Learn). The other two require free API keys (Google Developer Knowledge, Data Commons). If you don't configure the API keys, you'll see errors in the plugin UI — **these are harmless and all other commands work normally**.
+
+---
+
+## Bundled MCP Servers
+
+| MCP Server | API Key | Used By | Status |
+|------------|---------|---------|--------|
+| AWS Knowledge | Not required | `/arckit:aws-research` | Works out of the box |
+| Microsoft Learn | Not required | `/arckit:azure-research` | Works out of the box |
+| Google Developer Knowledge | `GOOGLE_API_KEY` | `/arckit:gcp-research` | Requires setup |
+| Data Commons | `DATA_COMMONS_API_KEY` | Data statistics lookups | Requires setup |
+
+---
+
+## No-Setup Servers
+
+### AWS Knowledge
+
+Provides access to official AWS documentation, service details, regional availability, and architecture guidance.
+
+- **Type**: HTTP (remote endpoint)
+- **Commands**: `/arckit:aws-research`
+- **Tools**: `search_documentation`, `read_documentation`, `get_regional_availability`, `list_regions`, `recommend`
+- **Setup**: None — works immediately after plugin installation
+
+### Microsoft Learn
+
+Provides access to official Microsoft and Azure documentation, code samples, and architecture guidance.
+
+- **Type**: HTTP (remote endpoint)
+- **Commands**: `/arckit:azure-research`
+- **Tools**: `microsoft_docs_search`, `microsoft_code_sample_search`, `microsoft_docs_fetch`
+- **Setup**: None — works immediately after plugin installation
+
+---
+
+## Servers Requiring API Keys
+
+### Google Developer Knowledge
+
+Provides access to Google Cloud documentation for GCP service research.
+
+- **Type**: HTTP (remote endpoint)
+- **Commands**: `/arckit:gcp-research`
+- **Tools**: `search_documents`, `get_document`, `batch_get_documents`
+
+**Setup**:
+
+1. Get a free API key from [Google AI Studio](https://aistudio.google.com/apikey) or the [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
+2. Set the environment variable:
+
+```bash
+# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
+export GOOGLE_API_KEY="your-api-key-here"
+```
+
+3. Restart Claude Code
+
+### Data Commons
+
+Provides access to public statistical data from Data Commons (demographics, economics, health, environment) for grounding architecture decisions in real-world data.
+
+- **Type**: HTTP (remote endpoint)
+- **Commands**: Used by research commands for data lookups
+- **Tools**: Various data query tools
+
+**Setup**:
+
+1. Get an API key from [Data Commons](https://datacommons.org)
+2. Set the environment variable:
+
+```bash
+# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
+export DATA_COMMONS_API_KEY="your-api-key-here"
+```
+
+3. Restart Claude Code
+
+> **Your keys stay hidden in `claude mcp` output.** Both keyed servers carry their key in an HTTP header (`X-Goog-Api-Key`, `X-API-Key`) via `${GOOGLE_API_KEY}` / `${DATA_COMMONS_API_KEY}`. As of Claude Code v2.1.161, `claude mcp list` / `get` / `add` no longer expand `${VAR}` references and redact credential headers and URL secrets — so inspecting your MCP config (or screen-sharing it) won't leak the keys. Relevant for OFFICIAL-SENSITIVE / regulated deployments. The other four bundled servers are keyless, so there's nothing to redact.
+
+---
+
+## Troubleshooting
+
+### "Missing environment variables" errors in plugin UI
+
+```text
+Invalid MCP server config for 'google-developer-knowledge': Missing environment variables: GOOGLE_API_KEY
+Invalid MCP server config for 'datacommons-mcp': Missing environment variables: DATA_COMMONS_API_KEY
+```
+
+**These errors are harmless.** They mean you haven't configured the optional API keys. All ArcKit commands, agents, hooks, and skills work without them. Only `/arckit:gcp-research` and Data Commons lookups are affected.
+
+**To fix**: Set the environment variables as described above and restart Claude Code.
+
+### MCP server not responding after setup
+
+1. Verify the environment variable is set: `echo $GOOGLE_API_KEY`
+2. Restart Claude Code (MCP servers load at startup)
+3. Check the plugin UI — errors should disappear once the key is valid
+
+### API key works but commands fail
+
+- **Google**: Ensure the API key has the "Generative Language API" enabled in Google Cloud Console
+- **Data Commons**: Ensure the key is active and not rate-limited
+
+---
+
+## Optional Third-Party MCPs
+
+ArcKit also supports integration with third-party MCP servers that are **not bundled** with the plugin. These must be configured per-project in your `.mcp.json`.
+
+| MCP | Purpose | Guide |
+|-----|---------|-------|
+| Pinecone | Vector search across architecture artifacts and Wardley Mapping knowledge base | [Pinecone MCP Guide](pinecone-mcp.md) |
+
+---
+
+## Configuration Reference
+
+The plugin's bundled MCP configuration (`.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "aws-knowledge": {
+      "type": "http",
+      "url": "https://knowledge-mcp.global.api.aws"
+    },
+    "microsoft-learn": {
+      "type": "http",
+      "url": "https://learn.microsoft.com/api/mcp"
+    },
+    "google-developer-knowledge": {
+      "type": "http",
+      "url": "https://developerknowledge.googleapis.com/mcp",
+      "headers": {
+        "X-Goog-Api-Key": "${GOOGLE_API_KEY}"
+      }
+    },
+    "datacommons-mcp": {
+      "type": "http",
+      "url": "https://api.datacommons.org/mcp",
+      "headers": {
+        "X-API-Key": "${DATA_COMMONS_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+> **Note**: You do not need to copy this configuration — it is automatically loaded by the plugin. This is shown for reference only.
+
+---
+
+## Complementary Skills for Architects
+
+Anthropic publishes document skills in the `anthropics/skills` marketplace that pair well with ArcKit. These skills let Claude produce polished, client-ready deliverables directly from ArcKit's Markdown artifacts.
+
+### Installing the document skills
+
+```text
+/plugin marketplace add anthropics/skills
+/plugin
+```
+
+Navigate to **Discover** > **anthropic-agent-skills** > **document-skills** and install.
+
+### Available document skills
+
+| Skill | What it does | Architecture use case |
+|-------|-------------|----------------------|
+| **PDF** (`/pdf`) | Create and edit PDF documents | Export requirements, risk registers, or business cases as formatted PDFs for stakeholder review |
+| **DOCX** (`/docx`) | Create and edit Word documents | Produce editable architecture documents for governance boards that require Word format |
+| **PPTX** (`/pptx`) | Create and edit PowerPoint presentations | Turn `/arckit:presentation` output or architecture summaries into slide decks for steering committees |
+| **XLSX** (`/xlsx`) | Create and edit Excel spreadsheets | Export evaluation matrices, risk scores, or FinOps data into spreadsheets for analysis |
+
+### Example workflows
+
+**Architecture board submission**:
+
+1. Run `/arckit:sobc` to generate a Strategic Outline Business Case
+2. Use `/docx` to convert it into a branded Word document with your organisation's template
+3. Use `/pptx` to create an executive summary deck from the key findings
+
+**Vendor evaluation pack**:
+
+1. Run `/arckit:evaluate` to score vendors
+2. Use `/xlsx` to export the evaluation matrix as a spreadsheet
+3. Use `/pdf` to create a sealed PDF for procurement records
+
+**Stakeholder briefing**:
+
+1. Run `/arckit:stakeholders` and `/arckit:requirements`
+2. Use `/pptx` to build a slide deck covering stakeholder map, goals, and top-level requirements
+3. Share with project sponsors for sign-off
+
+> **Note**: The document skills are maintained by Anthropic in a separate marketplace (`anthropics/skills`). They are not part of the ArcKit plugin but complement it well. They work in both Claude Code and Claude Cowork.
+
+For detailed workflows and real-world examples, see the [Architecture Productivity Guide](productivity.md).
+
+---
+
+## Resources
+
+- [AWS Knowledge MCP](https://awslabs.github.io/mcp/servers/aws-knowledge-mcp-server) — AWS documentation server
+- [Microsoft Learn MCP](https://learn.microsoft.com/api/mcp) — Azure documentation server
+- [Google Developer Knowledge MCP](https://developerknowledge.googleapis.com/mcp) — Google Cloud documentation server
+- [Data Commons](https://datacommons.org) — Public statistical data
+- [Model Context Protocol](https://modelcontextprotocol.io/) — MCP specification
+- [Anthropic Skills](https://github.com/anthropics/skills) — Document skills (PDF, DOCX, PPTX, XLSX)
+- [Claude Plugins Directory](https://claude.com/plugins) — Browse all available plugins

arckit_cli-6.1.1.data/data/share/arckit/docs/guides/migration.md

@@ -0,0 +1,333 @@
+# File Migration Playbook
+
+> **Guide Origin**: Official | **ArcKit Version**: [VERSION]
+
+`migrate-filenames.sh` converts legacy ArcKit filenames to the standardized Document ID naming convention.
+
+> **Platform note**: This migration script requires a bash shell (Linux, macOS, or Windows via Git Bash / WSL). It is a one-time migration utility and does not affect day-to-day ArcKit command usage.
+
+---
+
+## Overview
+
+ArcKit uses standardized Document IDs for all artifacts:
+
+```text
+ARC-{PROJECT_ID}-{TYPE}-v{VERSION}.md
+```
+
+Examples:
+
+- `ARC-001-REQ-v1.0.md` - Requirements for project 001
+- `ARC-001-ADR-001-v1.0.md` - First ADR for project 001
+- `ARC-000-PRIN-v1.0.md` - Global architecture principles
+
+---
+
+## Command
+
+```bash
+# Single project
+${CLAUDE_PLUGIN_ROOT}/scripts/bash/migrate-filenames.sh projects/001-my-project
+
+# Dry run (preview changes)
+${CLAUDE_PLUGIN_ROOT}/scripts/bash/migrate-filenames.sh projects/001-my-project --dry-run
+
+# All projects
+${CLAUDE_PLUGIN_ROOT}/scripts/bash/migrate-filenames.sh --all
+
+# Global directory only
+${CLAUDE_PLUGIN_ROOT}/scripts/bash/migrate-filenames.sh --global
+```
+
+---
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--dry-run` | Preview changes without modifying files |
+| `--all` | Migrate all projects in `projects/` directory |
+| `--global` | Migrate only `projects/000-global/` |
+| `--force` | Overwrite existing files if they exist |
+| `--no-backup` | Skip creating backup (not recommended) |
+| `--help`, `-h` | Show help message |
+
+---
+
+## File Mappings
+
+### Core Documents
+
+| Old Filename | Type Code | New Filename |
+|--------------|-----------|--------------|
+| `requirements.md` | REQ | `ARC-{PID}-REQ-v1.0.md` |
+| `stakeholder-drivers.md` | STKE | `ARC-{PID}-STKE-v1.0.md` |
+| `stakeholder-analysis.md` | STKE | `ARC-{PID}-STKE-v1.0.md` |
+| `risk-register.md` | RISK | `ARC-{PID}-RISK-v1.0.md` |
+| `sobc.md` | SOBC | `ARC-{PID}-SOBC-v1.0.md` |
+| `data-model.md` | DATA | `ARC-{PID}-DATA-v1.0.md` |
+| `research-findings.md` | RSCH | `ARC-{PID}-RSCH-v1.0.md` |
+| `traceability-matrix.md` | TRAC | `ARC-{PID}-TRAC-v1.0.md` |
+| `analysis-report.md` | ANAL | `ARC-{PID}-ANAL-v1.0.md` |
+
+### Global Documents (000-global)
+
+| Old Filename | Type Code | New Filename |
+|--------------|-----------|--------------|
+| `architecture-principles.md` | PRIN | `ARC-000-PRIN-v1.0.md` |
+| `principles.md` | PRIN | `ARC-000-PRIN-v1.0.md` |
+
+### Strategy & Operations
+
+| Old Filename | Type Code | New Filename |
+|--------------|-----------|--------------|
+| `project-plan.md` | PLAN | `ARC-{PID}-PLAN-v1.0.md` |
+| `roadmap.md` | ROAD | `ARC-{PID}-ROAD-v1.0.md` |
+| `backlog.md` | BKLG | `ARC-{PID}-BKLG-v1.0.md` |
+| `devops-strategy.md` | DEVOPS | `ARC-{PID}-DEVOPS-v1.0.md` |
+| `mlops-strategy.md` | MLOPS | `ARC-{PID}-MLOPS-v1.0.md` |
+| `finops-strategy.md` | FINOPS | `ARC-{PID}-FINOPS-v1.0.md` |
+| `operational-readiness.md` | OPS | `ARC-{PID}-OPS-v1.0.md` |
+| `servicenow-design.md` | SNOW | `ARC-{PID}-SNOW-v1.0.md` |
+| `platform-design.md` | PLAT | `ARC-{PID}-PLAT-v1.0.md` |
+
+### Procurement
+
+| Old Filename | Type Code | New Filename |
+|--------------|-----------|--------------|
+| `sow.md` | SOW | `ARC-{PID}-SOW-v1.0.md` |
+| `dos-requirements.md` | DOS | `ARC-{PID}-DOS-v1.0.md` |
+| `digital-marketplace-dos.md` | DOS | `ARC-{PID}-DOS-v1.0.md` |
+| `gcloud-requirements.md` | GCLD | `ARC-{PID}-GCLD-v1.0.md` |
+| `gcloud-clarification-questions.md` | GCLC | `ARC-{PID}-GCLC-v1.0.md` |
+| `evaluation-criteria.md` | EVAL | `ARC-{PID}-EVAL-v1.0.md` |
+
+### Compliance
+
+| Old Filename | Type Code | New Filename |
+|--------------|-----------|--------------|
+| `tcop-review.md` | TCOP | `ARC-{PID}-TCOP-v1.0.md` |
+| `tcop-assessment.md` | TCOP | `ARC-{PID}-TCOP-v1.0.md` |
+| `ukgov-secure-by-design.md` | SECD | `ARC-{PID}-SECD-v1.0.md` |
+| `secure-by-design.md` | SECD | `ARC-{PID}-SECD-v1.0.md` |
+| `mod-secure-by-design.md` | SECD-MOD | `ARC-{PID}-SECD-MOD-v1.0.md` |
+| `ai-playbook-assessment.md` | AIPB | `ARC-{PID}-AIPB-v1.0.md` |
+| `atrs-record.md` | ATRS | `ARC-{PID}-ATRS-v1.0.md` |
+| `jsp-936.md` | JSP936 | `ARC-{PID}-JSP936-v1.0.md` |
+| `jsp936.md` | JSP936 | `ARC-{PID}-JSP936-v1.0.md` |
+| `dpia.md` | DPIA | `ARC-{PID}-DPIA-v1.0.md` |
+| `principles-compliance-assessment.md` | PRIN-COMP | `ARC-{PID}-PRIN-COMP-v1.0.md` |
+
+### Reviews
+
+| Old Filename | Type Code | New Filename |
+|--------------|-----------|--------------|
+| `hld-review.md` | HLDR | `ARC-{PID}-HLDR-v1.0.md` |
+| `dld-review.md` | DLDR | `ARC-{PID}-DLDR-v1.0.md` |
+
+### Other
+
+| Old Filename | Type Code | New Filename |
+|--------------|-----------|--------------|
+| `PROJECT-STORY.md` | STORY | `ARC-{PID}-STORY-v1.0.md` |
+
+---
+
+## Subdirectory Handling
+
+### Multi-Instance Documents
+
+Files in these subdirectories are renamed with sequence numbers:
+
+| Subdirectory | Type Code | New Pattern |
+|--------------|-----------|-------------|
+| `decisions/` | ADR | `ARC-{PID}-ADR-{NNN}-v1.0.md` |
+| `diagrams/` | DIAG | `ARC-{PID}-DIAG-{NNN}-v1.0.md` |
+| `wardley-maps/` | WARD | `ARC-{PID}-WARD-{NNN}-v1.0.md` |
+| `data-contracts/` | DMC | `ARC-{PID}-DMC-{NNN}-v1.0.md` |
+| `research/` | RSCH | `ARC-{PID}-RSCH-{NNN}-v1.0.md` |
+
+### Research Files
+
+Root-level research files are moved to `research/` subdirectory:
+
+| Pattern | Migrated To |
+|---------|-------------|
+| `research-*.md` | `research/ARC-{PID}-RSCH-{NNN}-v1.0.md` |
+| `research.md` | `research/ARC-{PID}-RSCH-{NNN}-v1.0.md` |
+
+### Procurement Subdirectory
+
+Files in `procurement/` are migrated to the project root:
+
+```text
+Before:
+  projects/001-project/procurement/gcloud-requirements.md
+  projects/001-project/procurement/digital-marketplace-dos.md
+
+After:
+  projects/001-project/ARC-001-GCLD-v1.0.md
+  projects/001-project/ARC-001-DOS-v1.0.md
+```
+
+### Reviews Subdirectory
+
+HLD and DLD review files are moved to `reviews/`:
+
+```text
+Before:
+  projects/001-project/hld-review.md
+
+After:
+  projects/001-project/reviews/ARC-001-HLDR-v1.0.md
+```
+
+---
+
+## Legacy Locations
+
+### Global Principles
+
+The migration script checks these legacy locations for principles:
+
+| Legacy Location | Migrated To |
+|-----------------|-------------|
+| `.arckit/memory/architecture-principles.md` | `projects/000-global/ARC-000-PRIN-v1.0.md` |
+| `.arckit/memory/principles.md` | `projects/000-global/ARC-000-PRIN-v1.0.md` |
+
+### Root-Level Diagrams
+
+Files matching these patterns are moved to `diagrams/`:
+
+| Pattern | Migrated To |
+|---------|-------------|
+| `*-diagram.md` | `diagrams/ARC-{PID}-DIAG-{NNN}-v1.0.md` |
+| `diagram-*.md` | `diagrams/ARC-{PID}-DIAG-{NNN}-v1.0.md` |
+
+### Root-Level Wardley Maps
+
+Files matching these patterns are moved to `wardley-maps/`:
+
+| Pattern | Migrated To |
+|---------|-------------|
+| `*-wardley.md` | `wardley-maps/ARC-{PID}-WARD-{NNN}-v1.0.md` |
+| `*-map.md` | `wardley-maps/ARC-{PID}-WARD-{NNN}-v1.0.md` |
+
+---
+
+## Date-Suffixed Files
+
+Some compliance files have date suffixes. These are handled specially:
+
+| Pattern | Migrated To |
+|---------|-------------|
+| `principles-compliance-assessment-YYYY-MM-DD.md` | `ARC-{PID}-PRIN-COMP-v1.0.md` |
+| `service-assessment-*-prep.md` | `ARC-{PID}-SVCASS-v1.0.md` |
+
+---
+
+## Backups
+
+By default, the script creates a timestamped backup before making changes:
+
+```text
+projects/001-project/.backup/20260128_143022/
+├── requirements.md
+├── stakeholder-drivers.md
+└── risk-register.md
+```
+
+Use `--no-backup` to skip backups (not recommended).
+
+---
+
+## Examples
+
+### Preview All Changes
+
+```bash
+${CLAUDE_PLUGIN_ROOT}/scripts/bash/migrate-filenames.sh --all --dry-run
+```
+
+Output:
+
+```text
+[INFO] Migrating project: 001-payment-gateway (ID: 001)
+[DRY-RUN] Would rename: requirements.md → ARC-001-REQ-v1.0.md
+[DRY-RUN] Would rename: stakeholder-drivers.md → ARC-001-STKE-v1.0.md
+[DRY-RUN] Would rename: risk-register.md → ARC-001-RISK-v1.0.md
+[DRY-RUN] No changes made
+```
+
+### Migrate Global Principles
+
+```bash
+${CLAUDE_PLUGIN_ROOT}/scripts/bash/migrate-filenames.sh --global
+```
+
+This will:
+
+1. Create `projects/000-global/` if it doesn't exist
+2. Check `.arckit/memory/` for legacy principles files
+3. Migrate to `projects/000-global/ARC-000-PRIN-v1.0.md`
+
+### Migrate Single Project
+
+```bash
+${CLAUDE_PLUGIN_ROOT}/scripts/bash/migrate-filenames.sh projects/001-payment-gateway
+```
+
+### Force Overwrite Existing
+
+```bash
+${CLAUDE_PLUGIN_ROOT}/scripts/bash/migrate-filenames.sh projects/001-payment-gateway --force
+```
+
+---
+
+## Post-Migration Steps
+
+1. **Review backups**: Check `.backup/` directories for original files
+2. **Update references**: Search for old filenames in documentation
+3. **Run pages command**: Regenerate documentation site with `/arckit:pages`
+4. **Commit changes**: Add migrated files to version control
+
+---
+
+## Troubleshooting
+
+### "Cannot extract project ID"
+
+Project directories must follow the pattern `{NNN}-{name}`:
+
+- Valid: `001-payment-gateway`, `002-user-auth`
+- Invalid: `payment-gateway`, `project1`
+
+### "Target exists, skipping"
+
+A file with the new name already exists. Use `--force` to overwrite.
+
+### Files Not Migrated
+
+Check that the filename matches a known mapping. The script only migrates recognized ArcKit artifact names.
+
+---
+
+## Review Checklist
+
+- [ ] Ran `--dry-run` first to preview changes
+- [ ] Verified backup directory was created
+- [ ] Checked all expected files were migrated
+- [ ] Updated cross-references in documentation
+- [ ] Regenerated GitHub Pages with `/arckit:pages`
+- [ ] Committed changes to version control
+
+---
+
+## Key Principles
+
+1. **Non-destructive**: Original files are backed up before migration
+2. **Idempotent**: Already-migrated files are skipped
+3. **Predictable**: Consistent naming pattern across all projects
+4. **Traceable**: Document IDs enable cross-referencing