When you open an unconfigured code project, the SessionStart hook emits a one-line nudge offering to configure it. Saying "configure this project" or running /setup --detect scans the repo, renders a default-all-enabled proposal with a per-skill/per-hook rationale, and writes the approved enablement block to project.json on approval.

1. Open the unconfigured repo. The harness-context-session-start hook fires a single line each session until the repo is registered or .agentm-no-register is present:

   [agentm] New project — I haven't configured this repo. Say 'configure this project' or run /setup --detect.
   

2. Run the detection flow. Say "configure this project" or run /setup --detect. /setup runs detection as its first step (§0), before the inventory + interview:

   python3 scripts/detect_project.py . --format json   # structured proposal (drives agent logic)
   python3 scripts/detect_project.py . --format text   # operator-facing approval block

3. Read the proposed config block. Every enableable skill and hook starts enabled (✓); each line carries a rationale — a default reason, or a detection reason when a rule matched this repo. See Detection rules for the 10 rules and what each attaches a rationale to.

4. Choose a/b/c:

   • (a) Register with all-enabled — python3 scripts/project_config.py register .
   • (b) Register with custom selection — answer per-skill/per-hook (Enter keeps the default of enabled), then pass each decline: python3 scripts/project_config.py register . --disable <name> --disable <name>. Each --disable records an operator_overrides entry.
   • (c) Skip — touch .agentm-no-register. One-time scratch session; the nudge stays silent until you remove the marker.

5. On (a) or (b), finish registration. register writes the enablement block to project.json (see Project config) and registers the repo in the vault repo_registry. Then:

   • Create the project's charter.md at projects/<slug>/charter.md in the vault if it is absent. Confirm the project resolves with python3 scripts/process_seam.py project-path tasks --cwd ., which prints where its tasks live, or with python3 scripts/harness_memory.py list-plans (vault-state-path is retired — agentm-vault plan 15).
   • Accept or decline the offer to add a vault_slug: <slug> line to AGENTS.md (operator-confirmed; never silent).

6. Re-open the repo. python3 scripts/project_config.py is-registered . prints registered (exit 0) and the SessionStart nudge stays silent.

• Re-detect a configured project — re-run the scan once the repo has changed.
• Detection rules reference — the 10 built-in rules and what each detects.
• Project config reference — the project.json enablement-block schema this flow writes.
• Auto-detect + auto-configure — why the flow proposes-then-approves and why config lives in project.json.
• Install AgentM machine-wide — the one-time install that precedes first-session configuration.