Install

install

First-time setup, or resuming a partial one. skills.install.lib.install_state() is read at the start of EVERY stage below — a stage that's already done (per real on-disk state) is skipped, never redone or asked about twice. Exit criterion 6: a friend can install → onboard (within the question budget) → see the first-session artifact → work a week → update — without the founder present. This flow is that path.

Stages (idempotent — check install_state() before each)

1. Doctor quick-pass. A fast environment sanity check (framework version reachable, wiki root resolvable). Not a full /ren:doctor run — just enough to know setup can proceed. Also calls skills.install.lib.warm_environment(), which runs uv sync --frozen and records the venv's real interpreter path to state_dir()/interpreter.json (issue #11 §4). This is what lets the wake-up hook's self-heal re-exec directly under that interpreter instead of paying uv run's cold resolution cost (~7s on a fresh machine) — without it, a friend's very first session can trip the hook's timeout and run degraded ("memory injection DISABLED"). If uv isn't available or the sync/resolve fails, don't block the rest of install on it — log/report the failure and continue (the wake-up hook still falls back to its existing uv run self-heal path).
2. Stamp wiki — skills.install.lib.stamp_wiki(). Additive-only (per lib.skeleton's contract): if install_state().wiki_stamped is already True, this is a no-op report, not a re-stamp. This is the ONE non-skippable stage — nothing else here means anything without a wiki root to write into. Then call skills.install.lib.write_default_graph_config(), reporting "default graph view written" if a new file was created or "existing graph config kept" if one already existed.
   • Populated-wiki refusal. If stamp_wiki() raises PopulatedWikiError (the target wiki already holds real content — a project map, or a core page UPDATEd since founding), render exc.args[0] (the message) to the friend verbatim, mark this stage skipped, and continue with the remaining stages — the refusal is not fatal to install; a populated wiki means bootstrap already happened. There is no force flag and none is offered.
3. Global instruction layer — lib.adapter.claude_md.write_global_claude_md(). Writes/refreshes the RenOS managed block (between <!-- ren:begin -->/<!-- ren:end --> markers) in the user-level CLAUDE.md: the tailored behavioral core (omitted automatically if the friend's file already carries the Karpathy guidelines), the recall doctrine, wiki navigation, and the doctrine index (generated from lib.doctrine.loader — this is how always-on doctrine reaches every session). ONLY the marker block is ever touched — everything else in the friend's file is preserved byte-for-byte. If it returns "conflict" (torn markers from a hand edit), tell the friend which file to fix and move on; never force it. Skip silently when install_state().global_claude_md is True and the framework version hasn't changed.
4. Interview — delegates entirely to /ren:interview (see that skill). MAY BE SKIPPED ENTIRELY: if the friend says "skip to coding" (or equivalent), print exactly which defaults were assumed (skills.interview.lib.QUESTIONS' default values) and move on. identity.md already exists as a stub after stage 2 either way (the skeleton's copy_if_missing stamp) — the interview only UPDATEs it with real answers.
5. Backup setup offer. If install_state().backup_configured is True, skip silently. Otherwise offer to configure a backup git remote (see /ren:backup) and note that install nags until it's configured — this is the one recurring nag in the flow, per spec §3.9 "backup first-class." Also note: this isn't just a nag — lib.governance.backup_gate.require_backup (0.6.0 Task 4) makes a configured backup a hard precondition for /ren:ingest-project//ren:bootstrap-project once the wiki holds grown content (a fresh/empty wiki is unaffected, so the first-ever bootstrap in this same install flow still runs).
6. Companions — skippable. Call lib.companions.pending_offers(). If empty (everything already installed or decided), say so in one line and move on. Otherwise present each offer conversationally — title, one-line pitch, and the install hint — and ask which the friend wants. This is a multi-pick, not per-item nagging.
   • Accepted tool (kind == "tool"): run its install_hint command for them (it is always a uv tool install …), confirm it landed (shutil.which), then lib.companions.record_choice(cid, "accepted").
   • Accepted plugin (kind == "plugin"): show the install_hint for the friend to run themselves (plugin installs need a session restart to activate — say so plainly), then record_choice(cid, "accepted").
   • Declined: record_choice(cid, "declined") — a durable no; RenOS never asks about that companion again.
   • Stage skipped entirely: record nothing — the same offers reappear at the next /ren:install or /ren:update. Nothing is ever installed without an explicit yes in chat.
7. First project. Offer /ren:ingest-project <path> (an existing repo) or /ren:bootstrap-project <name> (a fresh idea) — either one ends with the FIRST-SESSION ARTIFACT (Task 4.4's ingest()/L2-map assembly): "I set up your project memory — here's what I captured," rendered from the real map that was just written. This is the cheapest trust-builder in the whole system (spec §3.8 A-10) — don't skip presenting it even if the friend picks "skip everything else."
8. Record + closing summary. skills.install.lib.record_install(current_framework_version), then a short summary: what you can do now — /ren:pin (remember something), /ren:recall (look something up), /ren:wrap (end-of-session consolidation), and re-running /ren:interview anytime to fill in more identity detail.

Idempotency contract

Every stage above is a no-op if install_state() already reports it done — re-running /ren:install from any point (interrupted session, friend re-invokes out of habit) picks up exactly where it left off. There is no separate "resume" command; install_state() inspecting real files IS the resume mechanism (donor's InstallSimulator existed to fake this same idea in tests; RenOS drives it against real state instead).

Test-driving install

The ONLY sanctioned way to exercise /ren:install against anything but the real wiki is REN_WIKI_ROOT=/path/to/scratch — the highest-precedence wiki override (lib/ren_paths.py:40). Never run a test install without it: pointed at the real wiki, a second stamp_wiki() call against real content now raises PopulatedWikiError (the 2026-08-12 incident, where a test run of install re-ADDed skeleton pages over real content) — the flow-level guard exists precisely so a test-drive can't silently corrupt a friend's actual memory.

Design notes

• Donor's 7-stage flow (env, required plugins, conditional plugins, identity, wiki bootstrap, doctor verify, walkthrough) maps to 8 stages here — RenOS ships as one plugin, so donor's plugin-negotiation stages don't apply; the global instruction layer (stage 3, finalize-v0.2 agenda item 1) takes their slot as the doctrine-delivery stage. Stage 6 (companions, 0.3.5) is new and has no donor counterpart — it offers the recommended companion tools/plugins from lib.companions.
• The question budget (skills.install.lib.QUESTION_BUDGET = 10) is enforced by skills.interview.lib.QUESTIONS's length, not re-checked here — install just delegates and trusts the cap.