archcore-ai/archcore/init

/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 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; init writes no global document and never joins a local and a global document 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: