arkgate 2.1.0

package/server.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.pedroknigge/arkgate",
+  "description": "ArkGate \u2014 architecture co-pilot for AI TypeScript (write gate, CI, plan/loop)",
+  "repository": {
+    "url": "https://github.com/pedroknigge/ark-runtime-kernel",
+    "source": "github"
+  },
+  "version": "2.1.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "arkgate",
+      "version": "2.1.0",
+      "runtimeHint": "npx",
+      "transport": {
+        "type": "stdio"
+      },
+      "packageArguments": [
+        {
+          "type": "positional",
+          "value": "arkgate-mcp"
+        },
+        {
+          "type": "named",
+          "name": "--root",
+          "value": ".",
+          "description": "Project root"
+        },
+        {
+          "type": "named",
+          "name": "--config",
+          "value": "ark.config.json",
+          "description": "Path to the ArkGate architecture config"
+        }
+      ]
+    }
+  ]
+}

package/templates/architecture-playbook.json

@@ -0,0 +1,339 @@
+{
+  "version": "1",
+  "locale": "en",
+  "localeNote": "Canonical user-facing copy is English. Future translations must not alter archetype ids, preset names, or layer names.",
+  "frontendSurfacePresetRule": "feature-sliced when src/app, src/pages, src/features, src/entities, or src/shared exists; otherwise layered",
+  "archetypes": {
+    "crud-product": {
+      "label": "Product with UI and stored data",
+      "preset": "hexagonal",
+      "phases": {
+        "1": [
+          "DomainModel",
+          "ApplicationOrchestration",
+          "PresentationAdapters",
+          "PersistenceAdapters"
+        ],
+        "2": ["IntegrationAdapters"],
+        "3": ["WorkflowSagaEngine", "BackgroundJobsScheduling"]
+      },
+      "analogy": "A restaurant: recipes (domain), kitchen coordinator (application), waiters (presentation), suppliers (adapters).",
+      "antiPatterns": [
+        "Database client or ORM imports inside domain/",
+        "HTTP or fetch calls inside business rules"
+      ],
+      "books": [
+        {
+          "title": "Clean Architecture",
+          "author": "Martin",
+          "for": "why business rules stay independent of UI and database"
+        }
+      ],
+      "detectionSignals": {
+        "ui": 5,
+        "persistence": 5,
+        "fullStackProduct": 4,
+        "domain": 1
+      },
+      "negativeSignals": {
+        "workspaces": 4,
+        "cli": 5,
+        "jobsOnly": 3,
+        "tinyTree": 2
+      }
+    },
+    "api-backend": {
+      "label": "API server without UI in this repository",
+      "preset": "hexagonal",
+      "phases": {
+        "1": [
+          "DomainModel",
+          "ApplicationOrchestration",
+          "PresentationAdapters",
+          "PersistenceAdapters"
+        ],
+        "2": ["IntegrationAdapters"],
+        "3": ["SecurityAuditObservability"]
+      },
+      "analogy": "A kitchen that only serves through a window: rules and coordination inside, orders in and out through adapters.",
+      "antiPatterns": [
+        "SQL or ORM calls mixed into route handlers without a repository layer",
+        "Domain rules that know HTTP status codes"
+      ],
+      "books": [
+        {
+          "title": "Implementing Domain-Driven Design",
+          "author": "Vernon",
+          "for": "application services and repository boundaries"
+        }
+      ],
+      "detectionSignals": {
+        "apiSurface": 6,
+        "persistence": 4,
+        "application": 2,
+        "nestFramework": 8,
+        "expressLike": 8
+      },
+      "negativeSignals": {
+        "uiHeavy": 5,
+        "workspaces": 3,
+        "cli": 5,
+        "tinyTree": 2,
+        "nextFramework": 4
+      }
+    },
+    "frontend-surface": {
+      "label": "UI-focused repository; backend lives elsewhere or is thin",
+      "preset": "layered",
+      "presetAlternatives": {
+        "feature-sliced": {
+          "whenSignal": "featureSlicedLayout"
+        }
+      },
+      "phases": {
+        "1": ["PresentationAdapters", "ApplicationOrchestration"],
+        "2": ["DomainModel"],
+        "3": ["IntegrationAdapters"]
+      },
+      "analogy": "A storefront display: what users see and click; inventory and payments happen behind the counter elsewhere.",
+      "antiPatterns": [
+        "Embedding database access in UI components",
+        "Business rules scattered across page files"
+      ],
+      "books": [
+        {
+          "title": "Feature-Sliced Design",
+          "author": "FSD community",
+          "for": "scaling a large UI codebase by feature slices"
+        }
+      ],
+      "detectionSignals": {
+        "ui": 6,
+        "featureSlicedLayout": 4,
+        "nextFramework": 5
+      },
+      "negativeSignals": {
+        "persistence": 5,
+        "apiSurfaceOnly": 3,
+        "workspaces": 2,
+        "cli": 5,
+        "tinyTree": 1,
+        "nestFramework": 6
+      }
+    },
+    "library-sdk": {
+      "label": "Publishable package others import",
+      "preset": "layered",
+      "phases": {
+        "1": ["DomainModel", "ApplicationOrchestration"],
+        "2": ["PersistenceAdapters"],
+        "3": ["IntegrationAdapters"]
+      },
+      "analogy": "A toolbox: clear public tools on top, internal parts hidden, no storefront of its own.",
+      "antiPatterns": [
+        "Leaking framework-specific types as the only public API",
+        "Hidden global state initialized on import"
+      ],
+      "books": [
+        {
+          "title": "Clean Architecture",
+          "author": "Martin",
+          "for": "stable boundaries for reusable modules"
+        }
+      ],
+      "detectionSignals": {
+        "library": 8,
+        "domain": 1
+      },
+      "negativeSignals": {
+        "ui": 4,
+        "cli": 3,
+        "workspaces": 3,
+        "persistenceHeavy": 2,
+        "nestFramework": 8,
+        "nextFramework": 8,
+        "apiSurface": 4
+      }
+    },
+    "cli-utility": {
+      "label": "Command-line tool",
+      "preset": "layered",
+      "phases": {
+        "1": ["ApplicationOrchestration"],
+        "2": ["PersistenceAdapters"],
+        "3": ["IntegrationAdapters"]
+      },
+      "analogy": "A vending machine panel: commands in, results out; storage and network are plug-ins behind the panel.",
+      "antiPatterns": [
+        "Business logic tangled with argv parsing and console output",
+        "Direct filesystem or network calls without a testable core"
+      ],
+      "books": [
+        {
+          "title": "Clean Architecture",
+          "author": "Martin",
+          "for": "separating use cases from delivery mechanisms"
+        }
+      ],
+      "detectionSignals": {
+        "cli": 10
+      },
+      "negativeSignals": {
+        "ui": 4,
+        "workspaces": 3,
+        "libraryOnly": 2,
+        "apiSurface": 6,
+        "expressLike": 6,
+        "nestFramework": 8,
+        "nextFramework": 8
+      }
+    },
+    "worker-pipeline": {
+      "label": "Background jobs and queues without a user-facing UI",
+      "preset": "hexagonal",
+      "phases": {
+        "1": ["ApplicationOrchestration", "PersistenceAdapters", "BackgroundJobsScheduling"],
+        "2": ["IntegrationAdapters"],
+        "3": ["ReportingReadModels"]
+      },
+      "analogy": "A night shift factory line: triggers arrive, work gets done, results stored — no shop floor for customers.",
+      "antiPatterns": [
+        "Job handlers that duplicate use-case logic from HTTP routes",
+        "Unbounded retries without idempotency at the domain boundary"
+      ],
+      "books": [
+        {
+          "title": "Building Microservices",
+          "author": "Newman",
+          "for": "async processing and integration boundaries"
+        }
+      ],
+      "detectionSignals": {
+        "jobs": 8,
+        "persistence": 2
+      },
+      "negativeSignals": {
+        "uiHeavy": 5,
+        "cli": 3,
+        "workspaces": 2
+      }
+    },
+    "event-coordinator": {
+      "label": "Long-running or multi-step business processes",
+      "preset": "hexagonal",
+      "phases": {
+        "1": ["DomainModel", "ApplicationOrchestration", "WorkflowSagaEngine"],
+        "2": ["IntegrationAdapters", "PersistenceAdapters"],
+        "3": ["ReportingReadModels"]
+      },
+      "analogy": "A wedding planner: many steps, compensations when something fails, state tracked across days.",
+      "antiPatterns": [
+        "Saga logic spread across unrelated HTTP handlers",
+        "Missing compensation when an external step fails"
+      ],
+      "books": [
+        {
+          "title": "Implementing Domain-Driven Design",
+          "author": "Vernon",
+          "for": "sagas and process managers"
+        }
+      ],
+      "detectionSignals": {
+        "workflows": 10,
+        "domain": 2
+      },
+      "negativeSignals": {
+        "cli": 4,
+        "tinyTree": 2,
+        "uiOnly": 3
+      }
+    },
+    "integration-bridge": {
+      "label": "Connects external systems with thin domain logic",
+      "preset": "hexagonal",
+      "phases": {
+        "1": ["IntegrationAdapters", "ApplicationOrchestration"],
+        "2": ["PersistenceAdapters"],
+        "3": ["BackgroundJobsScheduling"]
+      },
+      "analogy": "A translator at a border: messages in, messages out, minimal local rules.",
+      "antiPatterns": [
+        "Copy-paste integration code per webhook instead of shared adapters",
+        "Secrets and env access outside a dedicated config surface"
+      ],
+      "books": [
+        {
+          "title": "Building Microservices",
+          "author": "Newman",
+          "for": "integration patterns and boundaries"
+        }
+      ],
+      "detectionSignals": {
+        "integration": 8,
+        "apiSurface": 2
+      },
+      "negativeSignals": {
+        "uiHeavy": 4,
+        "domainHeavy": 3,
+        "workspaces": 2
+      }
+    },
+    "multi-app-workspace": {
+      "label": "Several deployable units in one repository",
+      "preset": "monorepo",
+      "phases": {
+        "1": ["DomainModel", "ApplicationOrchestration"],
+        "2": ["PresentationAdapters", "PersistenceAdapters"],
+        "3": ["IntegrationAdapters"]
+      },
+      "analogy": "A mall with separate shops sharing a parking lot: each app is a tenant, shared packages are utilities.",
+      "antiPatterns": [
+        "One package importing another app's internal directories",
+        "A single catch-all layer that hides cross-package coupling"
+      ],
+      "books": [
+        {
+          "title": "Monorepo.tools",
+          "author": "community",
+          "for": "workspace layout and dependency boundaries"
+        }
+      ],
+      "detectionSignals": {
+        "workspaces": 10
+      },
+      "negativeSignals": {
+        "cli": 2,
+        "tinyTree": 3
+      }
+    },
+    "prototype-spike": {
+      "label": "Fast experiment or learning project",
+      "preset": "layered",
+      "phases": {
+        "1": ["ApplicationOrchestration", "PersistenceAdapters"],
+        "2": ["DomainModel", "PresentationAdapters"],
+        "3": ["IntegrationAdapters"]
+      },
+      "analogy": "A sketch before the painting: enough structure to learn, expand when the idea stabilizes.",
+      "antiPatterns": [
+        "Adopting every layer on day one before the product shape is known",
+        "Skipping governance entirely because the repo is small"
+      ],
+      "books": [
+        {
+          "title": "Clean Architecture",
+          "author": "Martin",
+          "for": "growing structure as complexity appears"
+        }
+      ],
+      "detectionSignals": {
+        "tinyTree": 8
+      },
+      "negativeSignals": {
+        "workspaces": 5,
+        "workflows": 4,
+        "jobs": 3
+      }
+    }
+  }
+}

package/templates/policy-packs/enthusiast-feature-sliced.json

@@ -0,0 +1,20 @@
+{
+  "id": "enthusiast-feature-sliced",
+  "preset": "feature-sliced",
+  "variant": "enthusiast",
+  "label": "Feature-sliced — enthusiast",
+  "summary": "Organize by feature slices (App → Pages → Features → Entities → Shared). Start with App, Pages, and Features.",
+  "phases": {
+    "1": ["App", "Pages", "Features", "Shared"],
+    "2": ["Entities"],
+    "3": ["Widgets"]
+  },
+  "layerDescriptions": {
+    "App": "App shell — providers, routing, global styles.",
+    "Pages": "Full screens composed from features.",
+    "Widgets": "Large UI blocks built from features and entities.",
+    "Features": "User-facing actions (login, checkout, …).",
+    "Entities": "Business nouns shared across features.",
+    "Shared": "Buttons, utils, and UI kit with no business knowledge."
+  }
+}

package/templates/policy-packs/enthusiast-hexagonal.json

@@ -0,0 +1,18 @@
+{
+  "id": "enthusiast-hexagonal",
+  "preset": "hexagonal",
+  "variant": "enthusiast",
+  "label": "Hexagonal — enthusiast",
+  "summary": "Start with domain, application, presentation, and persistence. Add integrations and workflows when you need them.",
+  "phases": {
+    "1": ["DomainModel", "ApplicationOrchestration", "PresentationAdapters", "PersistenceAdapters"],
+    "2": ["IntegrationAdapters"],
+    "3": ["WorkflowSagaEngine", "BackgroundJobsScheduling"]
+  },
+  "layerDescriptions": {
+    "DomainModel": "Recipes — pure business rules and ports. No database, HTTP, or ambient globals.",
+    "ApplicationOrchestration": "Kitchen coordinator — use cases that call domain through ports only.",
+    "PresentationAdapters": "Waiters — UI, routes, and controllers that drive use cases.",
+    "PersistenceAdapters": "Suppliers — database, files, and external APIs implementing ports."
+  }
+}

package/templates/policy-packs/enthusiast-layered.json

@@ -0,0 +1,18 @@
+{
+  "id": "enthusiast-layered",
+  "preset": "layered",
+  "variant": "enthusiast",
+  "label": "Layered — enthusiast",
+  "summary": "Classic top-down layers: presentation → application → domain, with persistence at the bottom.",
+  "phases": {
+    "1": ["PresentationAdapters", "ApplicationOrchestration", "DomainModel", "PersistenceAdapters"],
+    "2": ["IntegrationAdapters"],
+    "3": ["BackgroundJobsScheduling"]
+  },
+  "layerDescriptions": {
+    "PresentationAdapters": "What users see and click — pages, components, HTTP handlers.",
+    "ApplicationOrchestration": "Business services and use-case coordination.",
+    "DomainModel": "Core rules and types — no I/O.",
+    "PersistenceAdapters": "Data access and infrastructure implementations."
+  }
+}

package/templates/policy-packs/enthusiast-monorepo.json

@@ -0,0 +1,18 @@
+{
+  "id": "enthusiast-monorepo",
+  "preset": "monorepo",
+  "variant": "enthusiast",
+  "label": "Monorepo — enthusiast",
+  "summary": "Several apps and packages in one repo. Match domain/application/presentation/persistence folder names in any package.",
+  "phases": {
+    "1": ["DomainModel", "ApplicationOrchestration"],
+    "2": ["PresentationAdapters", "PersistenceAdapters"],
+    "3": ["IntegrationAdapters"]
+  },
+  "layerDescriptions": {
+    "DomainModel": "Shared business types in packages — no I/O.",
+    "ApplicationOrchestration": "Shared use cases and services across apps.",
+    "PresentationAdapters": "Per-app entrypoints (pages, routes, components).",
+    "PersistenceAdapters": "Per-app or shared adapters for storage and APIs."
+  }
+}

package/templates/skills/ark-adopt.md

@@ -0,0 +1,103 @@
+---
+name: ark-adopt
+description: Onboard an existing codebase onto Ark — get the contract to reflect reality, classify ungoverned code, then freeze only genuine debt with a plan. Autonomous.
+---
+
+# /ark-adopt — Bring Ark into an existing codebase
+
+You are onboarding this repository onto Ark. The goal is NOT "make the check
+green" — it is to leave the project with a contract that reflects its real
+architecture, most of the code actually governed, and only genuine debt frozen
+with a plan to burn it down. A green check over a wrong contract or an ungoverned
+tree is a FALSE green — worse than no gate, because it looks safe. Work autonomously.
+
+Commands below are written as `ark-check` / `ark`; run each through the project's
+package manager — `pnpm exec ark-check …` in a pnpm repo, `yarn ark-check …` in a
+yarn repo, `npx ark-check …` under npm. Match the lockfile; never hardcode `npx` in
+a pnpm/yarn repo (AGENTS.md shows the exact runner for this project).
+
+## The guiding principle
+
+**Ark protects the boundary AROUND a framework, not its internals.** If the repo
+uses a DI/kernel framework (dcouplr, NestJS, a custom kernel), do NOT try to govern
+its inside — declare its PUBLIC SURFACE (the entrypoints app code is meant to
+import) as one layer and treat the rest as a black box. Governing the internals
+duplicates the framework's own wiring and fights it.
+
+## Steps
+
+1. **Config** — if `ark.config.json` is missing, run `ark-check --init`. It detects
+   the layer directories that exist, writes a config for them, and PROPOSES a layer
+   for every ungoverned directory (sourced from the 11-layer profile + presets),
+   flagging the ones it cannot place. If a config exists, keep it — don't regenerate
+   unasked.
+
+2. **Check + DIAGNOSE — before you freeze anything** — run
+   `ark-check --root . --config ark.config.json --json` and read `summary`: it groups
+   violations by edge, ranked. The critical signal is `summary.concentrated` /
+   `dominantShare`: **when most violations are a single edge, the CONTRACT is almost
+   always wrong, not the code.** (Real case: hundreds of API routes "violating"
+   app→kernel because the framework's own `defineRoute` is the sanctioned entrypoint
+   — false positives, not debt.) Investigate the dominant edge:
+   - App-land reaching a framework/kernel through a legitimate entrypoint → fix the
+     contract (step 3), do NOT freeze it.
+   - Unrelated layers genuinely importing each other → real debt for the baseline.
+
+3. **Make the contract reflect reality (via /ark-contract) BEFORE freezing:**
+   - **Classify the ungoverned tree.** Run `ark-check --coverage --json`; read
+     `governed.percent` and `suggestions`. If Ark governs a minority of the code, a
+     green check means almost nothing. Add the proposed layers for the recognized
+     directories; decide a layer for the ones flagged "unrecognized". Get `governed`
+     high before trusting any check.
+   - **Fix a concentrated edge at its source.** If the dominant edge is intended,
+     either allow it or — better — split the target layer into a PUBLIC SURFACE (the
+     entrypoints app code may import) and INTERNALS (denied). The breakdown's target
+     subtrees show where the surface is. This facade split turns a wall of false
+     positives into ~0 while still forbidding reach-arounds into internals.
+   Re-run the check; the remainder should now be the genuine minority.
+
+4. **Freeze the genuine debt** — run `ark-check --update-baseline`. If the set is
+   still lopsided on one edge, Ark REFUSES and tells you the contract still looks
+   wrong — heed it and return to step 3; do NOT `--force` past it just to get green.
+   On success it writes `.ark-baseline.json`; tell the user to commit it (don't commit
+   for them). From now `ark-check --baseline` fails only on NEW violations — the
+   ratchet only moves toward zero (fixing a frozen violation shrinks the baseline).
+
+5. **Gates + skills everywhere** — run `ark-check --install-agent-gates`. It
+   auto-detects the agent CLIs in the repo and writes the write gate, rule files,
+   package-manager-aware CI workflow, and the `/ark-*` skills for each (Kiro gets
+   only its steering rule; Copilot only via `--tools copilot`). If a baseline was
+   created, the generated CI already carries `--baseline`. For Codex, prompts load
+   from `$CODEX_HOME/prompts`, not the repo — install there too with
+   `ark-check --install-agent-gates --codex-home` (writes to their home dir; say so).
+
+6. **Ratchet plan** — from `summary.edges` (ranked), write a short prioritized
+   burn-down: which edge/cluster to fix first (biggest, or the one on the
+   most actively-edited files per `git log`), that `/ark-fix` resolves each, and
+   which items are real debt vs. deferred contract decisions.
+
+## Operating rules
+
+- Explain each step's WHY in one plain sentence — this is often the user's first
+  contact with Ark. Define jargon inline ("baseline = the list of violations that
+  existed before Ark, frozen so they don't block you while you fix them over time").
+- Do NOT chase green by freezing false positives or loosening the contract blindly.
+  The order is: contract reflects reality → classify → freeze only what's left.
+  Getting to green the wrong way is the exact failure this skill exists to prevent.
+- Don't overwrite customized files (`--force`) unless asked. Don't adopt the runtime
+  kernel here (that's `/ark-runtime`) — a repo with its own DI framework should keep it.
+
+## Related onboarding
+
+- **This skill is for brownfield** — existing messy repos. Do **not** use `/ark-architect` here.
+- Greenfield users: `/ark-architect`, `ark-check --recommend`, gallery starters (`examples/README.md`).
+- Demo: `docs/demos/02-brownfield-baseline-adoption.md`. Playbook: `docs/brownfield-adoption.md`.
+- Violation JSON may include `fixClass`, `effort`, `enthusiastHint` for burn-down ordering.
+
+## Verify and report
+
+Finish with `ark-check --root . --config ark.config.json --strict-config
+--baseline .ark-baseline.json` (omit `--baseline` if none) — it must pass. Report:
+governed % before/after, files written, violations frozen (and how many false
+positives you AVOIDED freezing by fixing the contract), the ratchet plan, and the
+commands the team needs (`check`, `/ark-fix`, `/ark-coverage`).

package/templates/skills/ark-architect.md

@@ -0,0 +1,90 @@
+---
+name: ark-architect
+description: Choose the application shape, adopt phase-1 layers, scaffold directories, and verify honestly — for enthusiasts before codegen. Autonomous.
+---
+
+# /ark-architect — Choose your application shape and adopt Ark
+
+The user is building something new or early in Ark adoption. They may not know
+layered architecture jargon. Your job: translate **what they want to build**
+(application shape, not framework name) into an Ark preset, a phase-1 layer plan,
+conventional directories, and a passing honest check — without weakening the gate.
+
+Commands below are written as `ark-check` / `ark`; run each through the project's
+package manager (`pnpm exec`, `yarn`, `npx`) — match the lockfile.
+
+## Relationship to other skills
+
+| Skill | When |
+|-------|------|
+| **/ark-architect** | **Before** — greenfield or fresh config; pick shape + phase 1 |
+| /ark-adopt | **After** — messy existing repo |
+| /ark-contract | **During** — evolve config safely |
+| /ark-place | **During** — one new file |
+| /ark-explain | **After** — understand what exists |
+
+## Steps
+
+1. **Detect the shape** — call MCP tool **`ark_recommend`** (or run
+   `ark-check --recommend --json`). Read `archetype`, `preset`, `confidence`,
+   `adoptInOrder.phase1`, `analogy`, and `why`. Ask at most **two** questions only
+   if `confidence < 0.5`:
+   - "Will this app save data between sessions?"
+   - "Is this one app or several in one repository?"
+
+2. **Present in plain English** — name the application shape (e.g. "product with
+   UI and stored data"), not the framework. One analogy. List **phase-1 layers only**.
+
+3. **Map to Ark** — if `ark.config.json` is missing, run
+   `ark init --archetype <archetype> --yes` (maps playbook id → preset + gates),
+   or `ark-check --apply-policy-pack enthusiast-<preset>` for the enthusiast variant.
+   Optional team record: `ark-check --recommend --write-plan` → `ark-adoption-plan.json`.
+   If a config already exists, use `/ark-contract` to align it — do not regenerate
+   unasked.
+
+4. **Scaffold phase 1** — create conventional directories from the preset/playbook
+   (`src/domain`, `src/application`, …). Add a one-line README per folder explaining
+   what belongs there. Match the nearest sibling file style if code already exists.
+   Flat layouts (`src/` + `lib/` + `api/` at the repo root) are common in Vite and
+   serverless projects — use `/ark-contract` to map them to layers instead of forcing
+   everything under `src/**/domain/**` only.
+
+5. **Install gates** when the user uses AI coding tools and gates are missing:
+   `ark-check --install-agent-gates`.
+
+6. **Verify honestly** — run `ark-check --doctor` and `ark-check --coverage --json`.
+   Report `governed.percent`. Say explicitly what is **not** governed yet
+   (ungoverned directories, empty layers).
+
+7. **Deliver to the user**
+   - ASCII diagram (≤3 boxes for phase 1, inner → outer)
+   - Table: "when you build X, put it in Y"
+   - Three rules the agent must not break (no domain→database imports, no raw
+     `publish()`, no weakening `ark.config.json` to pass)
+   - Optional book refs from `books` in the recommendation JSON under "go deeper"
+   - **Gallery starter** — point the user at the matching clonable example:
+
+     | Archetype | Example directory |
+     |-----------|-------------------|
+     | `crud-product` | `examples/crud-product-starter/` |
+     | `api-backend` | `examples/api-backend-starter/` |
+     | `worker-pipeline` | `examples/worker-pipeline-starter/` |
+     | `multi-app-workspace` | `examples/multi-app-workspace-starter/` |
+
+     Say they can copy that folder as a baseline (`npm install && npm run check`).
+     For a runnable API with break exercises, mention `examples/hexagonal-order-api/`.
+     Full enthusiast track: `docs/enthusiast/README.md`.
+
+## Operating rules
+
+- Never weaken `ark.config.json`, the baseline, CI, or agent settings to pass.
+- Never invent layers outside the 11-layer profile or named presets.
+- Flag unrecognized dirs (`utils/`, `lib/`) — user must classify via `/ark-contract`.
+- Default to smallest viable phase 1; unlock phase 2 only when the user describes need.
+- All user-facing copy is **English**.
+
+## Verify and report
+
+End with `ark-check --root . --config ark.config.json --strict-config` when the
+tree is ready. Report: archetype + preset, directories created, governed %, and
+the next command if anything remains ungoverned.