Clarify newcomer onboarding surfaces

.beads/interactions.jsonl

@@ -129,7 +129,52 @@
 {"id":"int-e141ac19","kind":"field_change","created_at":"2026-04-01T11:01:24.260353Z","actor":"Andrei","issue_id":"sdplab-zxl","extra":{"field":"status","new_value":"in_progress","old_value":"open"}}
 {"id":"int-d980d8ce","kind":"field_change","created_at":"2026-04-01T11:06:19.600313Z","actor":"Andrei","issue_id":"sdplab-zxl","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: rebased branch off origin/main, dropped stray 8004cae from PR history, and force-pushed clean head to PR #68"}}
 {"id":"int-a5363673","kind":"field_change","created_at":"2026-04-01T11:11:59.432752Z","actor":"Andrei","issue_id":"sdplab-yy6","extra":{"field":"status","new_value":"in_progress","old_value":"open"}}
-{"id":"int-23b5fe99","kind":"field_change","created_at":"2026-04-01T11:26:28.627416Z","actor":"Andrei","issue_id":"sdplab-46m","extra":{"field":"status","new_value":"in_progress","old_value":"open"}}
-{"id":"int-969c11c6","kind":"field_change","created_at":"2026-04-01T13:04:47.906924Z","actor":"Andrei","issue_id":"sdplab-46m","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: replaced hardcoded dev/master branch assumptions with repo-default branch resolution in orchestrate/evidence paths, updated canonical main-branch runbooks, and verified with targeted tests plus full go quality gates, protocol check, and doc-sync."}}
-{"id":"int-5e625362","kind":"field_change","created_at":"2026-04-01T17:16:06.631785Z","actor":"Andrei","issue_id":"sdplab-ioj","extra":{"field":"status","new_value":"in_progress","old_value":"open"}}
-{"id":"int-d3220832","kind":"field_change","created_at":"2026-04-01T17:24:26.51622Z","actor":"Andrei","issue_id":"sdplab-ioj","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: restored sdp as a real submodule from the public GitHub remote, repointed the gitlink to a valid OSS commit, recreated the missing multi-repo runbook, and opened an OSS PR to codify the submodule source-of-truth contract."}}
+{"id":"int-ab68b478","kind":"field_change","created_at":"2026-04-01T19:05:15.301133Z","actor":"Andrei","issue_id":"sdplab-eib","extra":{"field":"status","new_value":"in_progress","old_value":"open"}}
+{"id":"int-df118e37","kind":"field_change","created_at":"2026-04-01T19:07:09.483867Z","actor":"Andrei","issue_id":"sdplab-eib","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Defined wave-1 curated intake policy for superpowers in docs/plans/2026-04-01-superpowers-curated-intake-wave-1.md and linked the canonical skills reference; created follow-up tasks sdplab-hhs, sdplab-rio, sdplab-yqp."}}
+{"id":"int-8dcddbc1","kind":"field_change","created_at":"2026-04-04T10:56:41.862364Z","actor":"Andrei","issue_id":"sdplab-9ih","extra":{"field":"status","new_value":"in_progress","old_value":"open"}}
+{"id":"int-1d87a0aa","kind":"field_change","created_at":"2026-04-04T11:14:24.137445Z","actor":"Andrei","issue_id":"sdplab-9ih","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"CI green on PR #70 after GitHub Actions upgrades and project entrypoint docs consolidation; follow-up filed for misleading auto-attestation context fields"}}
+{"id":"int-eeffd6ff","kind":"field_change","created_at":"2026-04-04T11:17:50.289843Z","actor":"Andrei","issue_id":"sdplab-n8w","extra":{"field":"status","new_value":"in_progress","old_value":"open"}}
+{"id":"int-69b3d4cc","kind":"field_change","created_at":"2026-04-04T11:34:39.113281Z","actor":"Andrei","issue_id":"sdplab-n8w","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Review tail fixed: CI auto-attestation now reports branch, sdplab beads IDs, scoped boundary semantics, and pinned golangci-lint results on PR #70"}}
+{"id":"int-0896f345","kind":"field_change","created_at":"2026-04-04T11:35:59.079248Z","actor":"Andrei","issue_id":"sdplab-g77","extra":{"field":"status","new_value":"in_progress","old_value":"open"}}
+{"id":"int-6d7b5f12","kind":"field_change","created_at":"2026-04-04T11:47:30.280048Z","actor":"Andrei","issue_id":"sdplab-g77","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Review tail fixed: auto-attestation now checks out pull_request.head.sha and reports the real PR head commit in PR #70"}}
+{"id":"int-650dd334","kind":"field_change","created_at":"2026-04-04T11:56:24.81657Z","actor":"Andrei","issue_id":"sdplab-8ra","extra":{"field":"status","new_value":"in_progress","old_value":"open"}}
+{"id":"int-d1d2bada","kind":"field_change","created_at":"2026-04-04T12:02:08.949847Z","actor":"Andrei","issue_id":"sdplab-8ra","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged PR #70 into main and verified push CI green on run 23978394493"}}
+{"id":"int-020dc049","kind":"field_change","created_at":"2026-04-04T12:18:15.385858Z","actor":"Andrei","issue_id":"sdplab-cur","extra":{"field":"status","new_value":"in_progress","old_value":"open"}}
+{"id":"int-3f580a2e","kind":"field_change","created_at":"2026-04-04T12:39:03.451574Z","actor":"Andrei","issue_id":"sdplab-cur","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Cleaned docs/superpowers-curated-intake, merged PR #71 into main, and verified main CI run 23978985623 green"}}
+{"id":"int-9666ed70","kind":"field_change","created_at":"2026-04-04T12:51:09.08271Z","actor":"Andrei","issue_id":"sdplab-6az","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Moved primary checkout to main, aligned sdp submodule to recorded gitlink, pruned stale local branches, and kept only the local .beads runtime diff"}}
+{"id":"int-226369ba","kind":"field_change","created_at":"2026-04-04T13:01:40.79935Z","actor":"Andrei","issue_id":"sdplab-3ks","extra":{"field":"status","new_value":"in_progress","old_value":"open"}}
+{"id":"int-e28a8c54","kind":"field_change","created_at":"2026-04-04T13:05:14.222887Z","actor":"Andrei","issue_id":"sdplab-3ks","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: clarified that .beads-sdp-mapping.jsonl is helper-only, removed false 1:1 coverage assumptions from canonical docs, and cleaned mixed-format legacy mapping rows"}}
+{"id":"int-1c8aaa00","kind":"field_change","created_at":"2026-04-04T13:38:33.948411Z","actor":"Andrei","issue_id":"sdplab-vb6","extra":{"field":"status","new_value":"in_progress","old_value":"open"}}
+{"id":"int-610c35e9","kind":"field_change","created_at":"2026-04-04T13:46:02.483844Z","actor":"Andrei","issue_id":"sdplab-vb6","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: clarified newcomer and dev-agent onboarding in sdp_lab, plus public sdp onboarding truth for IDE support and greenfield/brownfield entrypoints"}}
+{"id":"int-a4170007","kind":"field_change","created_at":"2026-04-04T14:12:14.224754Z","actor":"Andrei","issue_id":"sdplab-7hv","extra":{"field":"status","new_value":"in_progress","old_value":"open"}}
+{"id":"int-c0e62cb5","kind":"field_change","created_at":"2026-04-04T14:41:02.700639Z","actor":"Andrei","issue_id":"sdplab-7hv","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: installer update paths now refresh managed assets and vendored checkout, dirty managed checkouts fail clearly, detached-HEAD CI coverage is in place, and both sdp PR #120 and sdp_lab PR #73 are green"}}
+{"id":"int-7a976d87","kind":"field_change","created_at":"2026-04-04T17:12:07.489158Z","actor":"Andrei","issue_id":"sdplab-3rm","extra":{"field":"status","new_value":"in_progress","old_value":"open"}}
+{"id":"int-1081ef2e","kind":"field_change","created_at":"2026-04-04T17:12:07.879163Z","actor":"Andrei","issue_id":"sdplab-3rm","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Fixed sdp init --auto first-run hang and scaffold creation"}}
+{"id":"int-9a0a2ce2","kind":"field_change","created_at":"2026-04-04T17:47:56.591266Z","actor":"Andrei","issue_id":"sdplab-s3m","extra":{"field":"status","new_value":"in_progress","old_value":"open"}}
+{"id":"int-68a52dac","kind":"field_change","created_at":"2026-04-04T17:47:58.221236Z","actor":"Andrei","issue_id":"sdplab-had","extra":{"field":"status","new_value":"in_progress","old_value":"open"}}
+{"id":"int-b14b36bb","kind":"field_change","created_at":"2026-04-04T18:23:41.934299Z","actor":"Andrei","issue_id":"sdplab-s3m","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: dry-run init output is truthful, non-duplicative, and no longer creates false .sdp/.claude signals"}}
+{"id":"int-17501bc0","kind":"field_change","created_at":"2026-04-04T18:23:41.994542Z","actor":"Andrei","issue_id":"sdplab-had","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: Codex is now first-class in installer/init/doctor/docs with verified install and update path"}}
+{"id":"int-f5b45af5","kind":"field_change","created_at":"2026-04-04T18:30:22.508195Z","actor":"Andrei","issue_id":"sdplab-bmi","extra":{"field":"status","new_value":"in_progress","old_value":"open"}}
+{"id":"int-5fa41995","kind":"field_change","created_at":"2026-04-04T18:31:25.494703Z","actor":"Andrei","issue_id":"sdplab-bmi","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: first-run doctor/init UX now stays focused for Codex and other non-Claude projects"}}
+{"id":"int-3799bb0a","kind":"field_change","created_at":"2026-04-04T18:40:50.499931Z","actor":"Andrei","issue_id":"sdplab-5dz","extra":{"field":"status","new_value":"in_progress","old_value":"open"}}
+{"id":"int-d01f0c6a","kind":"field_change","created_at":"2026-04-04T18:42:28.475389Z","actor":"Andrei","issue_id":"sdplab-5dz","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: fresh Claude installer path no longer reports managed .claude as a conflict during init"}}
+{"id":"int-8870d1fc","kind":"field_change","created_at":"2026-04-04T19:06:12.116613Z","actor":"Andrei","issue_id":"sdplab-wo6","extra":{"field":"status","new_value":"in_progress","old_value":"open"}}
+{"id":"int-dc28c8b2","kind":"field_change","created_at":"2026-04-04T19:12:31.613137Z","actor":"Andrei","issue_id":"sdplab-wo6","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: installer now prints configured integrations, clear next steps, and explicit fallback guidance"}}
+{"id":"int-117ad938","kind":"field_change","created_at":"2026-04-04T19:17:58.171143Z","actor":"Andrei","issue_id":"sdplab-072","extra":{"field":"status","new_value":"in_progress","old_value":"open"}}
+{"id":"int-4a54b521","kind":"field_change","created_at":"2026-04-04T19:24:32.069159Z","actor":"Andrei","issue_id":"sdplab-072","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: sdp skill now auto-detects project-local skills directories across Claude, Cursor, OpenCode, and Codex"}}
+{"id":"int-8ec28c04","kind":"field_change","created_at":"2026-04-04T19:37:02.070973Z","actor":"Andrei","issue_id":"sdplab-gph","extra":{"field":"status","new_value":"in_progress","old_value":"open"}}
+{"id":"int-6fb4baee","kind":"field_change","created_at":"2026-04-04T19:38:25.77008Z","actor":"Andrei","issue_id":"sdplab-gph","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: quality coverage command test is now deterministic, and go test ./cmd/sdp completes without timeout"}}
+{"id":"int-d70ba584","kind":"field_change","created_at":"2026-04-05T08:21:30.347091Z","actor":"Andrei","issue_id":"sdplab-6w4","extra":{"field":"status","new_value":"in_progress","old_value":"open"}}
+{"id":"int-23c14984","kind":"field_change","created_at":"2026-04-05T08:22:07.801833Z","actor":"Andrei","issue_id":"sdplab-6w4","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: doctor command tests now stub host-dependent checks and verify command wiring deterministically"}}
+{"id":"int-e5b5529f","kind":"field_change","created_at":"2026-04-05T09:43:14.729206Z","actor":"Andrei","issue_id":"sdplab-6w4","extra":{"field":"status","new_value":"in_progress","old_value":"closed"}}
+{"id":"int-9e4171cf","kind":"field_change","created_at":"2026-04-05T09:43:21.193516Z","actor":"Andrei","issue_id":"sdplab-6w4","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: doctor command tests now stub host-dependent checks and verify command wiring deterministically"}}
+{"id":"int-26cd260f","kind":"field_change","created_at":"2026-04-05T09:43:21.228075Z","actor":"Andrei","issue_id":"sdplab-uly","extra":{"field":"status","new_value":"in_progress","old_value":"open"}}
+{"id":"int-f8dcc43e","kind":"field_change","created_at":"2026-04-05T09:44:27.209245Z","actor":"Andrei","issue_id":"sdplab-uly","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: deploy command tests now stub git defaults and verify default output deterministically"}}
+{"id":"int-2ae4538d","kind":"field_change","created_at":"2026-04-05T10:03:16.142228Z","actor":"Andrei","issue_id":"sdplab-iir","extra":{"field":"status","new_value":"in_progress","old_value":"open"}}
+{"id":"int-ca19bbb4","kind":"field_change","created_at":"2026-04-05T10:05:57.211265Z","actor":"Andrei","issue_id":"sdplab-mkv","extra":{"field":"status","new_value":"in_progress","old_value":"open"}}
+{"id":"int-a82a0bfb","kind":"field_change","created_at":"2026-04-05T10:08:48.757787Z","actor":"Andrei","issue_id":"sdplab-mkv","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: canonical happy path consistency design written with modes, truth model, stage model, surface ownership, and rollout phases"}}
+{"id":"int-79bb3929","kind":"field_change","created_at":"2026-04-05T10:26:18.759707Z","actor":"Andrei","issue_id":"sdplab-5fk","extra":{"field":"status","new_value":"in_progress","old_value":"open"}}
+{"id":"int-af79d1e4","kind":"field_change","created_at":"2026-04-05T10:29:50.563288Z","actor":"Andrei","issue_id":"sdplab-5fk","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done: sdp_lab canonical docs now point to one stable happy-path reference, Operator Mode is explicit, and deferred runtime changes are captured in separate specs"}}
+{"id":"int-e47dca6c","kind":"field_change","created_at":"2026-04-05T10:34:09.214698Z","actor":"Andrei","issue_id":"sdplab-rzk","extra":{"field":"status","new_value":"in_progress","old_value":"open"}}
+{"id":"int-54f54eb5","kind":"field_change","created_at":"2026-04-05T10:48:16.558186Z","actor":"Andrei","issue_id":"sdplab-rzk","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Done"}}
+{"id":"int-130168d3","kind":"field_change","created_at":"2026-04-05T10:48:16.97244Z","actor":"Andrei","issue_id":"sdplab-0s1","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Done"}}

AGENTS.md

@@ -11,6 +11,23 @@ Use these entrypoints before diving into older plans or runbooks:
 3. [docs/architecture/REPO-BOUNDARY.md](docs/architecture/REPO-BOUNDARY.md) — what belongs in `sdp_lab` vs `sdp`
 4. [docs/roadmap/ROADMAP.md](docs/roadmap/ROADMAP.md) — current platform-first direction
 
+## Cold Start For Development Agents
+
+If you enter this repo cold, answer these before doing real work:
+
+1. Am I changing `sdp_lab`, or am I actually being asked to adopt or publish through `sdp/`?
+2. Is the user asking for platform work, or for "use SDP in my project" onboarding?
+3. Which single `feature`, `workstream`, or `beads issue` owns this task?
+4. Which doc is canonical for this question, instead of a historical plan?
+
+Minimum first pass:
+
+1. `git status --short --branch`
+2. read [docs/reference/project-map.md](docs/reference/project-map.md)
+3. if this is execution work, run `scripts/beads_transport.sh fetch` and `bd ready --json`
+4. if the request is about greenfield or brownfield SDP adoption, stop reading private-lab process docs and jump to [sdp/docs/QUICKSTART.md](sdp/docs/QUICKSTART.md)
+5. if the path starts with `sdp/`, read [docs/MULTI-REPO-WORKFLOW.md](docs/MULTI-REPO-WORKFLOW.md) before editing anything
+
 ## Project Structure
 
 This project has **two repos** with different roles:

README.md

@@ -1,14 +1,38 @@
 # SDP Lab Control Workspace
 
-Private planning and orchestration workspace for SDP evolution.
+Private build, planning, and orchestration workspace for SDP.
 GitHub repo name: `sdp_lab`. Historical docs and bead IDs may still use `sdp_dev` as a legacy label for the same root repo.
 
+## What This Repo Actually Does
+
+`sdp_lab` is the private repo where we build and steer the SDP platform itself.
+
+- platform code lives here: Go binaries, orchestration, evals, adapters, K8s manifests
+- planning lives here: roadmap, workstreams, private design docs, execution runbooks
+- public protocol artifacts live in `sdp/`: prompts, hooks, schemas, and OSS CLI work
+
+If your goal is to **use SDP inside your own project**, this repo is not the primary onboarding surface. Start with [`sdp/docs/QUICKSTART.md`](sdp/docs/QUICKSTART.md).
+
 ## Rules
 
 - This repo is the default place for strategic planning.
 - Do not publish private architecture, enterprise scope, or commercial details into OSS repos.
 - Export to OSS only through sanitized artifacts.
 
+## Choose Your Path
+
+| Goal | Start here |
+|---|---|
+| Understand what `sdp_lab` is and what lives here | [`docs/reference/project-map.md`](docs/reference/project-map.md) |
+| Contribute to the platform or private lab runtime | [`AGENTS.md`](AGENTS.md), [`docs/MULTI-REPO-WORKFLOW.md`](docs/MULTI-REPO-WORKFLOW.md), [`docs/roadmap/ROADMAP.md`](docs/roadmap/ROADMAP.md) |
+| Adopt SDP in a greenfield or brownfield project | [`sdp/docs/QUICKSTART.md`](sdp/docs/QUICKSTART.md), then [`sdp/README.md`](sdp/README.md) |
+
+## IDE Support Today
+
+- public onboarding flow is first-class for `Claude Code`, `Cursor`, and `OpenCode` / `Windsurf`
+- `Codex` prompt compatibility exists in [`sdp/.codex/`](sdp/.codex/), but the public install flow is still manual rather than auto-detected
+- if the question is "can I give SDP my keys and start working?", the honest answer lives in `sdp/`, not in the private-lab runbooks here
+
 ## Start Here
 
 Use these as the canonical entrypoints:
@@ -20,7 +44,14 @@ Use these as the canonical entrypoints:
 
 This README is a broad inventory, not the canonical workflow doc.
 
-## Folders
+## Main Components
+
+- `cmd/`, `internal/` - platform binaries, orchestration, evals, kernel, adapters
+- `deploy/` - deployable runtime and observability manifests
+- `docs/roadmap/`, `docs/workstreams/`, `docs/plans/` - planning and execution surfaces
+- `sdp/` - public submodule for prompts, hooks, schemas, and OSS CLI work
+
+## Inventory
 
 - `docs/architecture/REPO-BOUNDARY.md` - sdp vs sdp_lab boundary (binaries, publish mapping).
 - `docs/MULTI-REPO-WORKFLOW.md` - parent repo vs submodule commit order, branch defaults, and recovery steps.

docs/MULTI-REPO-WORKFLOW.md

@@ -1,5 +1,7 @@
 # sdp_lab <-> sdp Workflow
 
+If your real goal is "install SDP into my own repo and start using it", leave this doc and go to [../sdp/docs/QUICKSTART.md](../sdp/docs/QUICKSTART.md). This file is only for contributors working across the private parent repo and the public submodule.
+
 Use this repo as a two-repo workspace:
 
 | Path | Repo | Remote | Typical change |