Clarify onboarding paths and IDE support

.codex/INSTALL.md

@@ -8,19 +8,31 @@ Project skills source of truth lives in `prompts/skills/` (this repo). Tool fold
 
 ## Quick start
 
-1. Install SDP CLI (from repo root):
+1. Install SDP into your project with Codex integration:
    ```bash
-   cd sdp-plugin && CGO_ENABLED=0 go build -o sdp ./cmd/sdp && mv sdp ../
+   SDP_IDE=codex curl -sSL https://raw.githubusercontent.com/fall-out-bug/sdp/main/install.sh | sh
+   ```
+2. Run project init:
+   ```bash
+   sdp init --auto
    ```
-2. Ensure `sdp` is on PATH.
 3. Use `@build 00-XXX-YY` or `sdp plan`, `sdp apply`, `sdp log trace` per [CLAUDE.md](../CLAUDE.md).
 
+If you want the CLI only, use:
+
+```bash
+curl -sSL https://raw.githubusercontent.com/fall-out-bug/sdp/main/install.sh | sh -s -- --binary-only
+```
+
 ## Directory layout
 
 ```
 .codex/
 ├── INSTALL.md   # This file (read by Codex)
-└── skills/      # Project-level symlinks to prompts/skills
+├── agents/      # Project-level agent symlink
+└── skills/
+    ├── README.md
+    └── sdp/     # Project-level skills sourced from prompts/skills
 
 ~/.codex/
 └── skills/      # User-level skills (persistent)
@@ -29,3 +41,7 @@ Project skills source of truth lives in `prompts/skills/` (this repo). Tool fold
 ## Beads (optional)
 
 If Beads is installed (`bd --version`), use `bd ready`, `bd update`, `bd close` for task tracking. See [AGENTS.md](../AGENTS.md).
+
+## Updates
+
+Rerun the same installer command to refresh the vendored `sdp/` checkout and managed Codex links after upstream changes.

.codex/skills/sdp

@@ -0,0 +1 @@
+../../prompts/skills

.github/workflows/go-ci.yml

@@ -90,6 +90,12 @@ jobs:
           set -euo pipefail
           ../scripts/test-root-installer.sh
 
+      - name: Project installer regression check
+        shell: bash
+        run: |
+          set -euo pipefail
+          sh ../scripts/test-install-project.sh
+
       - name: Check for contracts
         id: check_contracts
         run: |

CONTRIBUTING.md

@@ -1,189 +1,148 @@
-# Contributing to Spec-Driven Protocol
+# Contributing to SDP
 
-Thank you for your interest in contributing!
+Thank you for contributing.
 
-**New contributors:** See [DEVELOPMENT.md](DEVELOPMENT.md) for setup instructions.
+Start with [DEVELOPMENT.md](DEVELOPMENT.md) for local setup and build commands.
 
 ## Ways to Contribute
 
-- **Report bugs** — Open an issue describing the problem
-- **Suggest features** — Open an issue with your idea
-- **Improve documentation** — Fix typos, add examples, clarify explanations
-- **Add skills** — Create new agent skills in `prompts/skills/`
-- **Add agents** — Create new agent definitions in `prompts/agents/`
-- **Share integrations** — Document how you use SDP with other tools
+- Report bugs with a reproducible example
+- Improve onboarding and reference docs
+- Fix CLI behavior in `sdp-plugin/`
+- Improve prompt and agent definitions in `prompts/`
+- Add or document integrations for supported harnesses
 
 ## Getting Started
 
-1. Fork the repository
-2. Clone your fork:
-   ```bash
-   git clone https://github.com/YOUR_USERNAME/sdp.git
-   cd sdp
-   ```
-3. Create a branch:
-   ```bash
-   git checkout -b feature/your-feature-name
-   ```
-
-## Project Structure
+1. Fork the repository.
+2. Clone your fork.
+3. Create a branch for one coherent change.
 
+```bash
+git clone https://github.com/YOUR_USERNAME/sdp.git
+cd sdp
+git checkout -b feature/your-feature-name
 ```
+
+## Repository Layout
+
+```text
 sdp/
-├── sdp-plugin/           # Go implementation (CLI + agents)
-│   ├── cmd/              # CLI commands
-│   └── internal/         # Core logic
-├── src/sdp/              # Go source (graph, monitoring, synthesis)
-├── tests/                # Go test suite
-├── prompts/
-│   ├── skills/           # Canonical AI skill definitions (source of truth)
-│   └── agents/           # Canonical multi-agent definitions (source of truth)
-├── .claude/
-│   ├── skills -> ../prompts/skills   # Compatibility symlink
-│   └── agents -> ../prompts/agents   # Compatibility symlink
-├── .cursor/              # Cursor IDE integration
-├── .opencode/            # OpenCode integration
-├── docs/
-│   ├── PROTOCOL.md       # Core specification
-│   ├── reference/        # API and command reference
-│   ├── vision/           # Strategic vision documents
-│   ├── drafts/           # Feature specifications
-│   ├── decisions/        # Architecture Decision Records
-│   └── workstreams/      # Backlog and completed WS
-├── hooks/                # Git hooks and validators
-├── templates/            # Workstream templates
-├── PRODUCT_VISION.md     # Product vision v3.0
-├── CLAUDE.md             # Claude Code integration guide
-├── AGENTS.md             # Agent instructions
-└── go.mod                # Go module definition
+├── sdp-plugin/           # Go CLI implementation
+│   ├── cmd/              # CLI entry points
+│   └── internal/         # CLI/runtime packages
+├── src/sdp/              # Root-module Go packages
+├── prompts/              # Canonical prompt and agent source
+│   ├── commands/
+│   ├── skills/
+│   └── agents/
+├── .claude/              # Claude adapter around prompts/
+├── .cursor/              # Cursor adapter around prompts/
+├── .opencode/            # OpenCode adapter around prompts/
+├── .codex/               # Codex adapter around prompts/
+├── docs/                 # Onboarding, protocol, and reference docs
+├── hooks/                # Validation and git-hook support
+├── schema/               # JSON schemas and contracts
+└── templates/            # Project and workflow templates
 ```
 
-## Go Module Structure (WS-067-10)
-
-SDP uses two separate Go modules:
+## Build and Test
 
-| Module | Location | Module Path | Purpose |
-|--------|----------|-------------|---------|
-| **Root** | `go.mod` | `github.com/fall-out-bug/sdp` | Core libraries (src/sdp/) |
-| **Plugin** | `sdp-plugin/go.mod` | `github.com/fall-out-bug/sdp` | CLI implementation |
+SDP currently uses Go `1.26` in both the root module and `sdp-plugin/`.
 
-### Building
+Build the CLI:
 
 ```bash
-# Build CLI (primary development)
-cd sdp-plugin && CGO_ENABLED=0 go build -o sdp ./cmd/sdp
-
-# Build root module (if needed)
-go build ./...
+cd sdp-plugin
+CGO_ENABLED=0 go build -o sdp ./cmd/sdp
 ```
 
-### Testing
+Run the main CLI test suite:
 
 ```bash
-# Test CLI module
-cd sdp-plugin && go test ./...
-
-# Test root module
+cd sdp-plugin
 go test ./...
 ```
 
-### Why No go.work?
-
-Both modules share the same module path (`github.com/fall-out-bug/sdp`), which prevents using Go workspaces. See [ADR-001](docs/decisions/ADR-001-dual-module-structure.md) for the consolidation decision.
-
-## Using SDP for Contributions
+Run root-module tests when your change touches root packages:
 
-For larger changes, use the SDP workflow:
+```bash
+go test ./...
+```
 
-1. **Requirements** — Run `@idea "description"` to create draft
-2. **Design** — Run `@design idea-{slug}` to create workstreams
-3. **Implement** — Run `@build 00-FFF-SS` for each workstream
-4. **Review** — Run `@review F{FF}` to verify quality
-5. **Deploy** — Run `@deploy F{FF}` when ready
+If you change installer behavior, also run:
 
-## Pull Request Process
+```bash
+sh scripts/test-install-project.sh
+```
 
-1. **Update documentation** if your change affects usage
-2. **Write clear commit messages** (conventional commits)
-3. **One feature per PR**
-4. **Reference issues** in PR description
+## What to Edit
 
-### PR Title Format
+- Edit `prompts/` for prompt or agent behavior.
+- Do not hand-edit `.claude/`, `.cursor/`, `.opencode/`, or `.codex/skills/sdp` as source files.
+- Edit `sdp-plugin/` for CLI behavior.
+- Update docs when public behavior changes.
 
-```
-type: brief description
+If docs and runtime disagree, fix docs to match shipped behavior. Do not document planned behavior as if it already exists.
 
-Examples:
-- docs: add integration example
-- feat: add @refactor skill
-- fix: correct dependency resolution
-```
+## Using SDP While Contributing
 
-## Code Style
+Two workflows exist today:
 
-- **Go** — Follow standard Go conventions, `gofmt`
-- **Markdown** — Consistent formatting, no trailing whitespace
-- **Skills** — Follow `prompts/skills/` SKILL.md format
+- **Local Mode:** `sdp init`, `sdp doctor`, `sdp plan`, `sdp apply`, `sdp verify`, `sdp status`, `sdp next`
+- **Operator Mode:** prompt surfaces plus Beads-backed queue management
 
-### Go Style
+For most contributors, Local Mode is the simplest way to exercise the current product.
 
-Use modern stdlib idioms that are supported by the repo's Go version.
+If you use prompt surfaces during development, treat them as harness-specific adapters over the same stage model. Important distinction:
 
-- Prefer `slices.SortFunc` over `sort.Slice`
-- Prefer `strings.Cut` over `strings.SplitN(..., 2)` or manual `strings.Index` slicing
-- Prefer `strings.CutPrefix` or `strings.CutSuffix` over prefix or suffix checks plus trim
-- Prefer `slices.Contains`, `maps.Copy`, and `maps.Clone` over handwritten helper loops
-- Prefer `any` over `interface{}` when behavior and public contracts stay the same
-- Use `golangci-lint` or `staticcheck` instead of `golint`
+- `sdp deploy` records an approval event after merge
+- `sdp deploy` does not merge your branch or deploy infrastructure
 
-For agent-driven Go work, load `@go-modern` before making style or cleanup changes.
+## Pull Requests
 
-## PR Checklist
+Before opening a PR:
 
-Before submitting a PR, ensure:
+- run the relevant Go tests for the code you changed
+- update user-facing docs when behavior changed
+- keep prompt edits in `prompts/`
+- keep one feature or fix per PR
+- reference the issue or problem statement in the PR description
 
-- [ ] Go version is 1.24 (`go version`)
-- [ ] Tests pass (`cd sdp-plugin && go test ./...`)
-- [ ] Coverage ≥80% (`go test -cover ./... | grep total`)
-- [ ] Guard checks pass (`./sdp guard check --staged`)
-- [ ] Prompt edits are in `prompts/` only (not `.claude/` or `sdp-plugin/prompts/`)
-- [ ] No `.out`, `bin/`, or `dist/` files staged
-- [ ] Run drift check: `./hooks/check-prompt-drift.sh`
-- [ ] Update relevant documentation if behavior changed
+Suggested PR titles:
 
-## Canonical Prompt Paths
+```text
+docs: clarify codex onboarding
+feat: add init preflight check
+fix: correct apply status output
+```
 
-**CRITICAL:** All prompt/agent definitions have a single canonical location.
+## Code and Doc Style
 
-| Content | Canonical Path | Symlink |
-|---------|---------------|---------|
-| Skills | `prompts/skills/` | `.claude/skills` |
-| Agents | `prompts/agents/` | `.claude/agents` |
+- Go: standard Go formatting with `gofmt`
+- Markdown: short sentences, clear headings, concrete examples
+- Prompts: keep canonical source in `prompts/`
 
-**Rules:**
-1. **Never create duplicate prompt files** in other locations
-2. **Always edit canonical files** in `prompts/`
-3. **Tool adapters** should reference canonical paths or symlinks
-4. **CI validates** no duplicate prompt trees exist
+Modern Go guidance used in this repo:
 
-To check for drift: `./hooks/check-prompt-drift.sh`
+- Prefer `slices.SortFunc` over `sort.Slice`
+- Prefer `strings.Cut` over manual split or index logic
+- Prefer `strings.CutPrefix` and `strings.CutSuffix` over trim-after-check
+- Prefer `slices.Contains`, `maps.Copy`, and `maps.Clone` over handwritten loops
+- Prefer `any` over `interface{}`
 
-## Generated Files
+## Prompt Source of Truth
 
-The following directories contain generated artifacts and should not be committed:
+All prompt and agent definitions have one canonical source:
 
-| Directory | Description | Why Ignore |
-|-----------|-------------|------------|
-| `.contracts/` | API contracts generated from code | Derived from source, regenerable |
-| `.oneshot/` | Checkpoint files | May contain sensitive state |
-| `docs/decisions/` | Local decision logs | Local audit trail only |
+| Content | Canonical path |
+|---------|----------------|
+| Commands | `prompts/commands/` |
+| Skills | `prompts/skills/` |
+| Agents | `prompts/agents/` |
 
-These are configured in `.gitignore`. If you see them in your working tree, do not commit them.
+Tool-specific directories are adapters. Edit `prompts/`, not the adapters.
 
 ## License
 
-By contributing, you agree that your contributions will be licensed under the MIT License.
-
----
-
-**Version:** 0.10.0
+By contributing, you agree that your contributions are licensed under the MIT License.