version: "1.0.0" name: init argument-hint: "[import|refresh] [path or domain]" description: "First-time Archcore setup. Wires the host (MCP config, hooks, CLAUDE.md/AGENTS.md managed block), measures the authored context the repo already holds, then composes a first-day seed — stack rule, run guide, data-model, integrations, config, entry points, public surface, a linked architecture overview, and specs for the top hotspot modules — shown in ONE preview and created on a single confirm. Modes, named as the first word: init import converts the repo's authored context — CLAUDE.md, AGENTS.md, .cursor/rules and other agent instructions, ADR and RFC folders, contributor docs, internal pages of a published docs site, recoverable git history — into native typed documents with no import marks, staged by a plan when the volume is large; init refresh adds facts that appeared since, or drills into one domain with init refresh <domain>. Use on a fresh clone, empty .archcore/, 'set up archcore', 'migrate our CLAUDE.md to archcore', 'import our docs and ADRs', or to wire host configs. Not for individual docs or planning."

/archcore:init

First-time onboarding. Wires the host, measures the authored context the repository already holds, and fills .archcore/ from two sources — what people wrote and what the code shows — so the code-alignment hook and per-command grounding have substance from day one. Per magic-first-day-init.adr and init-import-mode.adr: extractive facts are composed in full; authored content wins over synthesized content on the same subject; the overview is an index, never a prose blob. Nothing is written before `confirm`.

Before planning or writing relations, load skills/_shared/relation-authoring.md. Apply its claim check to seed and import wiring after reading the endpoint content.

Arguments

The first word selects the run: import or refresh. These two words are the command's modes in the sense of command-surface-v2.spec. The rest of the arguments is the subject. No arguments, or any other first word, start a plain init.

• import [path] — convert the repository's authored context into native documents, at all five discovery levels of lib/sources.md; a path limits the run to that path. Resumes an open import plan when one exists.
• refresh [path or domain] — re-run on a seeded repo to add facts that appeared since (a new schema, config, or modules) and to retrofit host wiring. A subject scopes the top-up: an existing path wins; otherwise a detected domain slug runs the single-domain pass. Bypasses the "already seeded" early-exit.
• Depth and scale are not arguments. The preview offers the toggles depth:light|standard|deep (default standard) and scale:small|medium|large, where the user already sees each choice's cost (lib/seed-compose.md). Import has no depth.

When to use

• Empty .archcore/ — the SessionStart nudge points here.
• First session on a fresh clone / fresh install.
• User says: "initialize archcore", "set up archcore", "seed archcore", "first-time setup", "what should I do first".
• User says: "migrate our CLAUDE.md / AGENTS.md / cursor rules to archcore", "import our ADRs and docs", "move our docs into archcore" → import.

Not init (route elsewhere):

• Recording a specific decision → /archcore:document.
• Planning a feature → /archcore:plan.
• Documenting one module → /archcore:document.
• Codifying a team standard → /archcore:document (offers rule + guide continuation).
• Filing one external material or a finished report → /archcore:document <the report or material>.
• Reading applicable context before coding → automatic; the code-alignment hook injects it on file edits.
• Docs health audit → /archcore:review.

Routing table

Mode routing — evaluated top-to-bottom, first match wins.

Fill routing — what the assessment gate (step 5) decides on a plain init or a refresh. The extractive facts are composed in every row.

Scale routing (small / medium / large, and what each seeds) lives in _shared/grounding/detect-scale.md and lib/seed-compose.md. Tier-1 facts are seeded in any scale when detected — breadth scales with the repo, presence does not.

Follow-up routing — closing-message hand-offs. Init surfaces these as todos; MUST NOT auto-invoke.

Execution

Content voice: default to architectural prose — decisions, rationale, intent. See skills/_shared/precision-rules.md Rule 6. Code blocks only where the document type requires it (rule, guide, cpat, and spec examples) or the user asks.

Gating (write boundary). init_project() and the read-only MCP calls (list_documents, get_document, search_documents) are infrastructure — they run before the preview. Three groups of operations are gated:

• document writes: create_document, update_document, remove_document, add_relation;
• host-wiring writes: install_host_config / archcore init --agent — they touch files outside .archcore/, like .mcp.json and .claude/settings.json;
• the source-file edits of the import track's retire gate.

No gated operation fires before the user types `confirm`. Absence of an answer is never confirm: IF this invocation cannot receive further user input in this turn (a print-mode run, a sub-agent call), THEN print the preview and stop. cancel therefore leaves .archcore/ content-empty and the repo's files untouched (the directory and settings.json may exist from init_project, which is harmless and idempotent).

Lazy reading. Load a flow file only when its step starts: lib/host-wiring.md at step 1, lib/sources.md at step 5, lib/seed-detect.md then lib/seed-compose.md at step 6, skills/_shared/tracks/import.md when a route reaches it. Never load them all at once.

1. Pre-flight — CLI and host-wiring gate

Run the CLI availability check and the cli-gte 0.7.0 host-wiring version gate per lib/host-wiring.md "Pre-flight". The canonical installer is documented at https://docs.archcore.ai/start/install/; never suggest another install channel. A missing CLI that the user declines to install stops the run. A CLI older than v0.7.0 continues with host wiring disabled.

2. Initialize and probe the host

Call mcp__archcore__init_project() exactly once (pre-gate infrastructure — idempotent, safe on an already-initialized project). It creates .archcore/ and settings.json if missing. On initialized: true print "Archcore initialized at `.archcore/`."; on already_initialized: true print nothing.

Then run the host and project-root probe per lib/host-wiring.md "Host and project root probe" — always, even when host wiring is disabled. It prints one token: claude-code | cursor | codex-cli | __UNKNOWN__. On __UNKNOWN__, or anything else than the three host tokens, ask one AskUserQuestion — "Which AI host is this session running in?" with options Claude Code / Cursor / Codex (CLI or desktop app) / GitHub Copilot CLI — and map the answer to the agent id (claude-code / cursor / codex-cli / copilot); there is no codex-desktop id. A GitHub Copilot CLI session always lands on __UNKNOWN__. Do not run archcore init yourself at this step; if the archcore MCP tools are unavailable in this session, the terminal command archcore init --agent <host> --project "<root>" is the user's recovery path.

Host wiring is planned first in every preview: when the probe finds the host configs absent, the Host wiring line leads the preview, and its writes lead the create phase.

3. Check state

Call mcp__archcore__list_documents() once. Derive every flag below from local documents only — skip any result carrying global: true / read_only: true / source_kind: "global". A mounted global source must not satisfy the already-seeded early-exit: init seeds THIS repo's documents. If any global results appear, load skills/_shared/globals.md; never modify a global document and never target one with add_relation. Derive:

• has_stack_rule — a rule whose title contains "stack" in conventions/; has_run_guide — a guide whose title contains "run"/"running" in onboarding/.
• has_data_model, has_integrations, has_config, has_entry_points, has_surface, has_top_level_map, has_overview — any doc tagged data-model, integrations, config, entry-points, surface, top-level-map, architecture-overview.
• open_import_plan — a local plan tagged import-plan.

Open import plan. On import, resume it (skills/_shared/tracks/import.md, "Track state and the import plan") and skip steps 4–5. On a plain init or a refresh, report it — rows done, rows open — and name /archcore:init import; plan no new conversion targets in this run.

Already-seeded early-exit. If has_stack_rule AND has_run_guide AND has_overview are all true AND the first word is neither refresh nor import, reply:

Init already seeded this repo. Applicable context auto-injects on file edits via the code-alignment hook; use /archcore:review on a branch with changes. To add facts that appeared since (a new schema, config, or modules), re-run /archcore:init refresh; to drill into one domain, /archcore:init refresh <domain>; to convert the repo's authored docs and agent instructions, /archcore:init import. (Seeded before host wiring existed, or missing the host configs? refresh also adds host wiring — MCP config, SessionStart hook, usage hint.)

Then stop. On a refresh run, skip this early-exit — every already-present artifact is marked skip (exists) in the preview and only missing ones are composed. Resolve a refresh subject here: an existing path → path scope; else a detected domain slug → single-domain pass; else ask one question that lists the detected domains.

4. Source-signal gate

Single filesystem probe — one shell call, no catalog reads:

• `has_manifest` — at least one project-defining manifest or build file at the project root (depth ≤ 2 for monorepo workspaces): package.json, pyproject.toml, requirements.txt, Cargo.toml, go.mod, Gemfile, composer.json, *.csproj, pom.xml, build.gradle*, mix.exs, Package.swift. Seed examples, not exhaustive — also CMakeLists.txt, Makefile, deps.edn, pubspec.yaml, build.sbt, *.cabal, *.tf, Chart.yaml, *.sln, and agent/LLM-plugin manifests such as marketplace.json / plugin.json / .claude-plugin/*.
• `has_top_level_source` — at least one file with a recognizable source extension under the project root, capped at depth 3, excluding .archcore/, .git/, node_modules/, vendor/, dist/, build/, out/, target/, coverage/, .venv/, __pycache__/, .next/, .turbo/. The extension list is not exhaustive — count any file whose contents are plainly source (a shebang, or import/include/package/module/def/func/class constructs).

If BOTH are false, do not decide yet — step 5 tells whether authored sources exist. Both false and no authored source → the empty route of lib/host-wiring.md (no placeholder documents, ever). Both false with authored sources → the import-only route.

5. Assessment gate

Skip on the import mode when step 3 resumed a plan. Otherwise read lib/sources.md and run the assess gate of skills/_shared/tracks/import.md in callable mode: list authored sources from paths, byte sizes, heading counts, and path mentions — never a full file body — with sizes computed only after stripping any archcore managed block (a file whose only content is the managed block is not a source). A plain init and a refresh assess levels L1–L2 — agent instructions (CLAUDE.md, AGENTS.md, .cursor/rules/*.mdc, .github/instructions/*.md, and the other L1 paths) and decision records; import assesses L1–L5. A plain init and a refresh also record deeper_present — a presence-only path listing of L3–L4 that feeds no measure.

The gate returns targets_est, tier, coverage_set, and levels_found. Announce them in one line, e.g.:

Authored context: 9 sources at L1–L2 (CLAUDE.md 6 KB, 6 .cursor/rules files, docs/adr × 2) → ~14 target documents, tier M. 2 hotspot modules look covered (estimate).

Print the line in every run, including the run that finds nothing. WHEN the gate returns no authored source (levels_found is empty), follow lib/sources.md "No authored source": a plain init or a refresh prints the "none" announce line and goes on to step 6 with the pool unchanged; the import mode prints the no-source report and stops — it MUST NOT fall back to the code seed, because the user asked for a conversion and the seed is a separate, costlier run.

6. Run the route

• Plain init / refresh — run lib/seed-detect.md (Phase A — DETECT), then lib/seed-compose.md (Phase B compose → Phase C preview → Phase D confirm → Phase E — CREATE + WIRE). The coverage_set narrows the hotspot pool in Phase A; the authored block of the preview follows the Fill routing table. One preview, one confirm.
• Import / import-only — run skills/_shared/tracks/import.md from its discover gate (or from the resumed row). Its plan preview carries the Host wiring line when wiring is absent. One confirm per wave when the plan grew; a separate confirm before any source file is edited.

7. Close

Seed runs close per lib/seed-compose.md "Closing message"; host-wiring outcome lines per lib/host-wiring.md. Import runs close with: documents created by type, the conflicts list, fidelity departures, rows still open with /archcore:init import as the continuation, and — after the last row — the retire offer and the removal of the import plan. Always end with:

Use /archcore:review on a branch with changes, /archcore:review audit the knowledge base for a health audit.

Result

A .archcore/ filled from two sources, created only on confirm; existing artifacts skipped.

• Empty: 0 content docs — .archcore/ and settings.json, plus host wiring behind its own mini-confirm. No catalog files read.
• Plain init: host wiring, the detected Tier-1 facts, the architecture overview, hotspot specs for the depth's budget over the pool that authored sources do not cover (the spec budget has no absolute maximum — standard 25% of the ranked pool, light 10%, deep 60%; lib/seed-compose.md), cross-cutting rules (medium/large), and — tier S — the converted authored documents, or — tier M/L — the import plan with wave 1 done. Every synthesized or converted document is status='draft'.
• No-source (import found nothing to convert): 0 documents, 0 file writes — a per-level report of what was checked, each skip with its class, and the next command.
• Import: native typed documents (rule, adr, rfc, guide, spec, doc, idea) clustered by topic across sources, linked to each other and to the seed facts where their claims support a relation; a conflicts list instead of silent choices; no imported tag, no source: tag, no pointer line, no imported- prefix. After the last wave: the retire offer for agent-instruction files, then the import plan is removed, so the corpus holds no record of the import.

Idempotency: the flagged Tier-1 facts and the overview are skip-on-exists; Tier-2 specs and rules dedupe by filename before create; conversion targets dedupe by a topic search before create and, for tiers M/L, by the import plan's row states. Host wiring is idempotent end-to-end. A second /archcore:init on a fully-seeded repo early-exits (step 3) unless refresh or import is the first word. The empty route never creates placeholder documents, so the SessionStart nudge keeps pointing here.