ArkGate 4.6.2 is on npm latest — first-contact copy (what to do in a few lines). 4.6.2 notes · 4.6.1 · 4.6.0 · Docs hub · Product voice

Choose your path

Full map: docs/README.md

Start in one minute

npm install -D arkgate typescript
npx arkgate start                 # preview files + commands
npx arkgate start --apply         # compact contract + host router + CI plan
npx arkgate-check --doctor        # control plane: status light + primary next action

That is the product. Doctor is the control plane — when stuck, do primary next action #1. Doctor also shows what to improve next (architecture lenses such as separation of concerns and dependency inversion — not a score). Leftover lenses mean design work may remain even when imports are green. Details: use.md — Improvement compass.

start → doctor (+ compass) → /ark-adopt (session 0) → day-to-day /ark-place
                         ↘ /ark-explore then /ark-autopilot when leftover design remains

Teams: keep the constitution out of product PRs. Local gate ark-check --changed --base origin/dev. Steward law PRs use --contract-session.

Aliases ark / ark-check / ark-mcp still work. npm / pnpm / yarn. No install lifecycle scripts.

What it is

A machine-readable architecture file (ark.config.json) plus enforcement:

Two planes (4.0)

Absence of ArkRules changes no inter-layer verdict. Label residual [Layer] vs [ArkRules].
Details: configuration · use path.

Not a web framework, ORM, or job runner. Optional experimental runtime is separate and not required for the gate.

Name note: npm package arkgate — not affiliated with the separate Archgate CLI project.

When not to adopt

ArkGate is overkill for small trees with no AI agents and no multi-layer boundaries, for single-developer hobby CRUDs under no integration pressure, and for teams that will not maintain ark.config.json or a required CI status running arkgate-check --strict-merge. In those cases stay with a boundary linter alone (see Why not only ESLint / Nx / cruiser?). Anyone path: docs/use.md — When not to adopt. Limits of a green check: 4.3.0 — What ArkGate is / isn't.

Status lights (not settings)

Details: docs/use.md.

Host enforcement support

Read the CI column: for every host, the repository-wide hard guarantee is a required GitHub status context that runs the CLI — not “CI file present,” and not the CLI binary name alone. Codex/OpenCode never get a fake hard write claim. Cursor hard write covers only listed preToolUse ops when .cursor/hooks.json is installed and trusted — Shell/Tab/human edits still rely on CI.

This table describes the supported profile after its files are installed and the host loads/trusts them. A hard local boundary covers only the listed hook operations; alternate tools, direct filesystem writes, and human edits still rely on CI. MCP validation is advisory because the agent must call it. The CI check blocks a merge only when the repository makes that status required. Repair envelopes may be emitted without reinjection being guaranteed; silent auto-apply never happens. Run arkgate-check --doctor (or ark-check --doctor) for the evidence actually detected in the current repository.

Why the hard guarantee lives at the merge gate

The split above is a deliberate trade-off, not a gap. ArkGate validates at the earliest boundary each host offers and enforces at the earliest boundary a repository can make non-bypassable: the required merge status. Hard hooks (Claude Code, Grok Build, Google Antigravity) deny the listed write operations at write time; advisory surfaces (MCP, rules, OpenCode plugins) coach the agent while it works. But any local boundary can be routed around — another tool, a direct filesystem write, a human edit — so the only guarantee ArkGate claims for every path is the arkgate-check --strict-merge check, and only when the repository makes that status required. Local checks optimize feedback speed; the merge gate owns correctness.

A useful consequence: the contract doubles as a pressure sensor. Recurring violations or baseline exceptions concentrated on one layer edge are evidence that the current design stopped fitting the code — a reason to reshape the contract deliberately (start with /ark-explore), never to weaken the gate.

Setup per host: docs/ai-gates.md · Develop path: docs/develop.md

For authoritative MCP contract evidence, call ark_identity with the exact project root, then call ark_manifest with that root plus the returned project id. A contained descendant requires the matching id. The legacy ark://manifest resource remains compatibility-only and always unverified/non-authoritative because standard resources/read cannot portably carry that expectation.

Why not only ESLint / Nx / cruiser?

Common commands

npx arkgate start --apply
npx arkgate status --json          # session/project snapshot (identity, activation, last check)
npx arkgate-check --doctor
npx arkgate-check --plan
npx arkgate-check --coverage
npx arkgate-check --strict-merge   # CI / required status
npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok
# optional: refresh shared home skills (Claude/Grok/Codex; never downgrades)
# npx arkgate-check --install-agent-gates --skills-only --agent-homes --force
# optional: same 13 skills via Agent Skills ecosystem (no new names)
# npx skills add ./node_modules/arkgate/templates/agent-skills

More: docs/develop.md · skills install: docs/agent-guide.md · enthusiast track: docs/enthusiast/

Optional experimental runtime

Gates need no app runtime. The experimental @arkgate/runtime companion is separate and is not a production-readiness claim.

Durability stance

Default stores (InMemoryEventBuffer, InMemoryAuditStore, InMemoryReadModelStore, InMemoryWorkflowStore) are reference in-memory only — fine for tests and demos; they do not survive restarts and are not production durability. Implement the store interfaces for real systems. Details: docs/production-hardening.md.

Documentation

Contribute to this library

git clone https://github.com/pedroknigge/arkgate
cd arkgate && npm ci && npm run build
npm test && npm run check:architecture

Full guide: CONTRIBUTING.md · queue: ROADMAP.md

Website: arkgate.online · npm: arkgate
MCP: io.github.pedroknigge/arkgate
Node ≥ 18 · MIT

Ark doesn’t invent your product. It keeps AI-generated TypeScript inside an architecture you can trust — and tells you when it isn’t really enforcing anything yet.