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.\nApply its claim check to seed and import wiring after reading the endpoint content.
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: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.domain, or a flag such as --refresh, --depth=deep, --scale=large — starts a plain init; name the current form once: \"/archcore:init [import|refresh] [path or domain]; depth and scale are toggles in the preview.\".archcore/ — the SessionStart nudge points here.import.Not init (route elsewhere):
\n/archcore:document./archcore:plan./archcore:document./archcore:document (offers rule + guide continuation)./archcore:document research./archcore:review.Mode routing — evaluated top-to-bottom, first match wins.
\n| Signal | \nRoute | \nFlow files | \n
|---|---|---|
First word import, and the assessment gate (step 5) finds no authored source | \n→ no-source: the no-source report; no gated operation, no confirm, no code seed | \nlib/sources.md \"No authored source\" | \n
First word import | \n→ import: the whole import track, levels L1–L5; no code seed | \nskills/_shared/tracks/import.md, lib/sources.md | \n
First word refresh | \n→ refresh: plain-init flow with the early-exit bypassed; existing artifacts are skip (exists) | \nas the plain rows below | \n
| Open import plan found (step 3) on a plain init | \n→ report the plan, name /archcore:init import, then continue the plain init without new conversion targets | \n— | \n
| No manifest, no source, no authored source (step 4) | \n→ empty: host wiring only, behind its own mini-confirm | \nlib/host-wiring.md \"Empty route\" | \n
| No manifest and no source, authored sources found | \n→ import-only: host wiring + the import track in one preview; no code seed | \nskills/_shared/tracks/import.md | \n
| Anything else | \n→ plain init: host wiring + facts + the fill the assessment gate divides | \nlib/seed-detect.md, lib/seed-compose.md | \n
Fill routing — what the assessment gate (step 5) decides on a plain init or a refresh. The extractive facts are composed in every row.
\n| Assessment result | \nAuthored sources | \nHotspot specs | \n
|---|---|---|
no authored source — nothing found, or every source found is skip | \nnone; the announce line names what was checked, and names /archcore:init import when deeper levels hold files | \nthe depth's budget over the unchanged ranked pool | \n
tier S (≤ 8 targets) | \nevery target listed in the init preview; converted on the init confirm | \nbudget over the pool minus the coverage_set | \n
tier M (9–40) or L (> 40) | \nthe init confirm creates the import plan and runs wave 1; the closing message names /archcore:init import | \nbudget over the pool minus the coverage_set | \n
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.
\n| User wants to... | \n→ Invoke | \n
|---|---|
| Continue an open import, or import beyond agent files and ADR folders | \n/archcore:init import | \n
| Import one folder only | \n/archcore:init import <path> | \n
| Add facts that appeared since first init | \n/archcore:init refresh | \n
| Drill into another domain (large) | \n/archcore:init refresh <domain> | \n
| Capture another module, record a decision, codify a convention | \n/archcore:document | \n
| Plan a feature | \n/archcore:plan | \n
| Scope queries to a domain (large) | \nmcp__archcore__search_documents with the domain tag | \n
| See what's loaded | \n/archcore:review | \n
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:
create_document, update_document, remove_document, add_relation;install_host_config / archcore init --agent — they touch files outside .archcore/, like .mcp.json and .claude/settings.json;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.
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.
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.
\nCall 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:
\n\nInit already seeded this repo. Applicable context auto-injects on file edits via the code-alignment hook; use
\n/archcore:reviewfor the dashboard. 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?refreshalso 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.
Single filesystem probe — one shell call, no catalog reads:
\nhas_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.
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.:
\n\nAuthored 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).
\n
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.
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.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.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:
\n\nUse
\n/archcore:reviewfor the dashboard,/archcore:review deepfor a health audit.
A .archcore/ filled from two sources, created only on confirm; existing artifacts skipped.
.archcore/ and settings.json, plus host wiring behind its own mini-confirm. No catalog files read.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'.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.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.