arka.norn is a local-first delivery framework for Projects, Features, attributed documents, human decisions, evidence, and auditable workflows.
It gives teams one durable recovery source: the published plan.
From a provider chat, an Agent can frame a Project or a Feature, connect that work to arka.norn, and continue across Web, TUI, and CLI without turning a SaaS workspace into the source of truth.
arka-norn
is the command.
Version 2.3.6 adds a post-install welcome and a grouped interactive menu, on top of the 2.3.5 branded setup and 'arka-norn version' update check. It builds on 2.3 orchestration control in Norn Web: preview a run, authorize it against the exact plan fingerprint, and apply a verified candidate under the 2.3 invariants, alongside Doctor inspect, preview, and repair, over the 2.3 live framing engine that frames a Project into Feature candidates or a Feature into bounded Lots and hands one exact published revision to the 2.3 delivery DAG.
Legacy 2.2 campaigns are inspection-only. Existing v4 Features keep their historical workflows. English remains canonical for contracts and machine data.
-
Start from a provider chat instead of a blank internal workflow
-
Recover from the published plan, not from chat history
-
Keep the human as the authority on scope, policy, and release
-
Operate locally across Web, TUI, and CLI
-
Produce attributed, integrity-verified, auditable, reproducible delivery artifacts
-
Node.js 22.13 or newer
-
npm
-
A local repository to manage
-
A registered and authenticated execution profile when automatic Agent execution is needed
-
Docker or Podman with the Project’s pinned recipe image already present for automatic tests and builds
Supported execution transports for automatic runs:
- Codex CLI
- Claude CLI
- Explicitly diagnosed API / Gemini profiles
npm install
npm run build
node bin/arka-norn.mjs --version
node bin/arka-norn.mjs doctor
Open the cockpit:
node bin/arka-norn.mjs
arka.norn does not replace the provider experience. It connects the Agent’s work to a durable local framework.
A typical flow is:
- You ask for work in a provider chat
- The Agent frames the task and links it to arka.norn
- arka.norn publishes an immutable, fingerprinted plan revision
- The same state becomes available in Web, TUI, and CLI
The plan is the recovery source. If the provider session changes, the Project state remains available through published local artifacts.
Live framing lets a connected Agent create a bounded, resumable plan before delivery.
arka-norn framing enter .
arka-norn framing enter . --new-feature "The outcome to deliver"
arka-norn framing show --view plan
arka-norn framing show --view evidence
arka-norn framing show --view map
arka-norn framing resume
The connected Agent updates the plan through bounded local deltas while the public CLI and Web interface expose human projections.
The plan, not the chat, is the recovery source.
Work in progress remains under $ARKA_NORN_HOME/framing
. Only a twice-stabilized, fingerprinted revision is published under the Project’s .arka-norn/plans
directory.
There are exactly two human stabilizations:
Repository grounding Authorizes grounding against the actual repository. - Publication and route binding Binds publication, decomposition, and the calculated delivery route.
Before the first stabilization, Norn probes the repository and adapts how it discovers the ground truth. It never runs a blind audit on an empty folder, and it never invents facts about code it has not read.
Empty— no audit and no code reader. Norn moves straight to explicitly greenfield technical design.** Skeleton**— reads only manifests and declared constraints.** Implemented**— performs a first intent-blind reading of the structure and public surfaces, then confronts those findings with the Product intent.Indeterminate— reduces its authority and avoids broad positive or negative claims.
Positive facts require the current snapshot and a file:line
anchor; absence claims require an inventory attestation.
Project plans produce Feature candidates without creating them in bulkFeature plans produce bounded Lots with scopes, dependencies, and proofs- A directly framed new Feature is materialized only after publication
Open Project tracking in the browser:
node bin/arka-norn.mjs web start
node bin/arka-norn.mjs web status
node bin/arka-norn.mjs web restart
node bin/arka-norn.mjs web stop
web
without an action is an alias for web start
.
The managed server runs in the background, survives the launching terminal, and opens the secured browser session by default.
Useful options:
--port 4317
--no-open
--json
web restart
preserves the current port and browser session. web stop
followed by web start
creates a new secure session. Use web foreground
only when the server must remain attached to the current terminal.
From a source checkout, the equivalent shortcuts are:
npm run web:start
npm run web:status
npm run web:restart
npm run web:stop
The Web interface presents:
- Project health
- Active framing
- Feature paths
- Attributed documents
- Decisions
- Audits
- Registered Agents
- Live Norn orchestration state
A Project prioritizes its current framing card. Plan, Evidence, Map, and History remain available after a provider or session change.
Starting a new Feature asks only for its expected outcome.
The CLI owns profile registration, preview, run authorization, recovery, and application. The TUI cannot relaunch quarantined 2.2 campaigns.
Project entry and Feature framing are guided for non-developers. Generated identifiers, folder choices, workflows, and advanced technical values stay out of the primary framing flow.
Automatic mode builds a confirmed, fingerprinted task DAG.
Every task gets its own:
- branch
- private Git worktree
- execution profile
- read/write scopes
- mechanical proof
Dependency-ready tasks with disjoint write scopes can run in parallel. Overlapping scopes are serialized before authorization.
Direct automatic execution no longer exists.
The human selects one provider/model profile per role and confirms:
- the plan
- the risk policy
- the commit authority
- the application policy
- the budget
- the parallelism
Agents have no native shell, Git, commit, network, or sub-agent authority.
All reads, proposed changes, Docker or Podman recipes, evidence, and decisions pass through the bounded Norn broker. Norn validates the result and creates the commit.
Choose the preferred tracking surface in Norn Web settings:
Web: functional explanations and a live read-only timeline, with no command blocks** TUI**: manual workflow and Agent identity management, with an explicit handoff to the 2.3 CLI for automatic runs** CLI**: exact commands and stable JSON for expert automation
See Automatic orchestration for workspace, budget, recovery, and application guarantees.
Install the generated Agent skills:
node bin/arka-norn.mjs install --global
node bin/arka-norn.mjs skills doctor
English is canonical for:
- code
- commands
- identifiers
- JSON fields
- schemas
- public documentation
Display text can be English or French.
arka-norn locale show
arka-norn locale set en
arka-norn locale set fr
arka-norn locale set auto
arka-norn --locale fr workflow list
ARKA_NORN_LOCALE=en arka-norn doctor
Resolution order is:
--locale
ARKA_NORN_LOCALE
- saved preference
- system locale
- English
Preferences are stored atomically in $ARKA_NORN_HOME/.arka-norn/preferences.json
and never enter portable Project or Feature markers.
Machine JSON always uses canonical English values. Only its display
block varies by locale.
| Workflow | Use it for | Required path |
|---|---|---|
| Essential 2.3 | New grounded Features with bounded Lots | development_report -> delivery_audit -> delivery_validation |
| Complete 2.3 | Grounded higher-risk Features whose downstream consumers require technical artifacts | Required technical contracts, delivery, audit, and validation |
| Essential legacy | Existing well-understood v4 Features | feature_brief -> development_report -> delivery_audit -> delivery_validation |
| Complete legacy | Existing v4 Features with the historical full document chain | Concept, plan, evidence, invariants, tasks, specification, delivery, and QA |
| FastDev | Small, bounded corrections and refactors | rework_brief -> development_report -> delivery_audit -> delivery_validation |
technical_contract_appendix
is optional in Essential.
Delivery audits can require a corrective development_report
. Validation always targets the latest report.
arka-norn workflow list
arka-norn workflow show essential
arka-norn essential start "Filter Features by status" --project product
arka-norn essential next <feature-id> --session <session-id> --json
Deprecated aliases standard
and essentiel
remain accepted with warnings throughout 2.x. Existing legacy Features continue on their French v3 contract until explicitly migrated.
The delivery chain remains attributed, integrity-verified, auditable, and machine-readable from framing to validation.
cd /workspace/product
arka-norn framing enter . --new-feature "Filter Features by status"
arka-norn framing resume
arka-norn framing show --view plan
arka-norn agent advise --project product --feature filter-features
arka-norn pipeline next filter-features --json
A v5 document uses English field names and declares the prose locale:
{
"schema_version": 5,
"content_locale": "fr",
"id": "brief-filter-features-01",
"feature_id": "filter-features",
"type": "feature_brief",
"sequence": 1,
"created_at": "2026-08-23T09:00:00.000Z",
"depends_on_document_ids": [],
"author_agent_id": "Codex_product_20260823"
}
The reader accepts legacy French v2/v3 Feature documents and Project audit v4 documents without rewriting them.
arka-norn migrate --target /workspace/product/feature
arka-norn migrate --target /workspace/product/feature --apply
Migration validates the whole Feature first, creates backups, preserves identity and graph relations, translates fields and enums, records the source version and SHA-256, and commits the marker last.
Unknown, mixed, or ambiguous contracts stop the entire operation.
Repeating a successful migration is a no-op.
Framing does not silently migrate existing Feature markers. Marker v4 remains on its historical pipeline. Marker v5 requires pipelineDefinitionVersion: 2.3
and an exact framingPlanRef
.
See Migration to live framing.
Public CLI JSON uses schemaVersion: 2
:
{
"schemaVersion": 2,
"command": "pipeline.status",
"ok": true,
"data": {},
"errors": [],
"warnings": [],
"diagnostics": {
"errors": [],
"warnings": []
},
"display": {
"locale": "en",
"errors": [],
"warnings": []
}
}
Scripts must depend on:
data
- stable diagnostic codes
- diagnostic parameters
They must never depend on localized display
prose.
User guideCLI referenceTUI guideProject Web guideEssential workflowFastDev workflowAgent guideAgent orchestrationDeveloper guideArchitectureSecurityTroubleshootingLive framing contractFraming Product and UX methodMigration to live framingStability contract 2.3
Canonical examples are under:
examples/feature-complete
examples/feature-essential
examples/feature-fastdev
examples/project-audit-v5
npm run lint
npm run typecheck
npm test
npm run selftest
npm run release:verify
npm run metrics:adoption
Source files are limited to 700 lines.
Canonical code and public documentation are checked for French text. Generated skills, examples, and Web locale catalogs come from shared canonical sources. Production Web assets are built into dist/web/
and shipped in the npm package.
metrics:adoption
is a maintainer-only, read-only report. It combines public npm download counts with the authenticated GitHub clone-traffic window exposed by gh
.
Use:
npm run metrics:adoption -- --json
for automation.
Norn itself includes no installation telemetry. npm downloads are not unique installations, and GitHub clone traffic covers only the rolling 14-day window.
.input/
is an ignored internal workspace. It is not packaged, published, or included in public CI.