finalize(v0.20.1): first-run polish + a11y + distribution audit

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,78 @@
+name: Bug report
+description: Something broke or behaved unexpectedly. Use this when the project did the wrong thing.
+title: "bug: "
+labels: ["bug", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for filing a bug. Please include the platform, version, install channel, and a minimal reproduction so we can confirm the failure quickly.
+
+  - type: input
+    id: version
+    attributes:
+      label: code-oz version
+      description: Output of `code-oz --version`
+      placeholder: "v0.20.1-alpha.0"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: install_channel
+    attributes:
+      label: Install channel
+      options:
+        - curl install script
+        - npm (@tuel/code-oz)
+        - Homebrew (omerakben/code-oz)
+        - Built from source
+    validations:
+      required: true
+
+  - type: dropdown
+    id: platform
+    attributes:
+      label: Platform
+      options:
+        - macOS arm64
+        - macOS x64
+        - Linux x64
+        - Linux arm64
+        - Other (please describe in the additional context section)
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Reproduction steps
+      description: A minimal sequence of commands that reproduces the bug. If a fixture is needed, link to it or paste it here.
+      placeholder: |
+        1. `code-oz init`
+        2. `code-oz run --effort lite`
+        3. ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: Include the relevant `events.jsonl` lines or `NEEDS_INTERVENTION.json` payload if applicable.
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: Logs, screenshots, related issues, anything else helpful.
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Discussion (questions, design, "is this the right approach")
+    url: https://github.com/omerakben/code-oz/discussions
+    about: For open-ended questions, design discussions, and "is this the right approach" conversations. Please use Discussions before filing a feature request issue.
+  - name: Security issue
+    url: https://github.com/omerakben/code-oz/security/advisories/new
+    about: Report security vulnerabilities privately via GitHub Security Advisories. See SECURITY.md for the full policy.

.github/ISSUE_TEMPLATE/demo_failure.yml

@@ -0,0 +1,74 @@
+name: Demo failure
+description: A bundled demo (`demo:todo-cli` or `demo:failure-gates`) did not produce the expected output.
+title: "demo: "
+labels: ["demo", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Demos are deterministic against `FakeProvider`. If a demo failed, that is a real bug. Please include the demo name, your platform, and the events.jsonl tail so we can reproduce.
+
+  - type: dropdown
+    id: which_demo
+    attributes:
+      label: Which demo
+      options:
+        - "demo:todo-cli (01-todo-cli)"
+        - "demo:failure-gates (02-failure-gates)"
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: code-oz version
+      placeholder: "v0.20.1-alpha.0"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: platform
+    attributes:
+      label: Platform
+      options:
+        - macOS arm64
+        - macOS x64
+        - Linux x64
+        - Linux arm64
+    validations:
+      required: true
+
+  - type: textarea
+    id: command
+    attributes:
+      label: Exact command(s) you ran
+      render: shell
+      placeholder: "bun run demo:failure-gates"
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected outcome
+      description: What did the demo's README say should happen? (Quote the relevant lines.)
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual outcome
+      description: Paste the relevant terminal output. If `events.jsonl` was produced, include the last 30 lines.
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: gate_files
+    attributes:
+      label: Gate files produced
+      description: Paste the contents of any `GATE_*.json`, `NEEDS_INTERVENTION.json`, `STOP.json`, or `PAUSE.json` produced by the failed run.
+      render: json
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,64 @@
+name: Feature request
+description: Propose a new capability, a new provider adapter, a new CLI flag, or a new gate.
+title: "feat: "
+labels: ["enhancement", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the proposal. Before filing, please skim [`docs/design/ROADMAP.md`](https://github.com/omerakben/code-oz/blob/main/docs/design/ROADMAP.md) to see if it is already on the roadmap.
+
+        Substantive features (new gate authority, new providers, new milestones) follow the milestone process described in [`CLAUDE.md`](https://github.com/omerakben/code-oz/blob/main/CLAUDE.md) — open a discussion first before filing the issue if you want feedback on the approach.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem
+      description: What is the user-facing problem this would solve? Why does it matter?
+    validations:
+      required: true
+
+  - type: textarea
+    id: workaround
+    attributes:
+      label: Current workaround
+      description: How are you handling this today (if at all)?
+    validations:
+      required: false
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed change
+      description: A sketch of the design — files touched, contract changes, new flags, new docs.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: What other shapes would solve the same problem? Why did you discard them?
+    validations:
+      required: false
+
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Estimated scope
+      options:
+        - Doc-only
+        - Small (one commit, no new authority)
+        - Medium (multi-commit, no new authority)
+        - Large (new gate, new provider, new milestone — needs design doc + Codex review)
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: rules
+    attributes:
+      label: Rule check
+      description: The 23 non-negotiable rules in `CLAUDE.md` are the project's authority. Substantive features must respect them.
+      options:
+        - label: I read the relevant rules in `CLAUDE.md` (e.g. rule 1 file-based gates; rule 17 maestro discipline; rule 20 one-authority-per-milestone; rule 22 RED-first TDD).
+          required: true

.github/ISSUE_TEMPLATE/install_problem.yml

@@ -0,0 +1,77 @@
+name: Install problem
+description: An install channel (curl, npm, Homebrew, source) failed for you.
+title: "install: "
+labels: ["install", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Install issues are high priority because they block first-run trust. Please include the channel, the platform, and the exact error output.
+
+  - type: dropdown
+    id: channel
+    attributes:
+      label: Install channel
+      options:
+        - curl install script
+        - npm (@tuel/code-oz)
+        - Homebrew (omerakben/code-oz)
+        - Built from source
+    validations:
+      required: true
+
+  - type: dropdown
+    id: platform
+    attributes:
+      label: Platform
+      options:
+        - macOS arm64
+        - macOS x64
+        - Linux x64
+        - Linux arm64
+        - Other (please describe below)
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Target code-oz version
+      placeholder: "v0.20.1-alpha.0"
+    validations:
+      required: true
+
+  - type: textarea
+    id: command
+    attributes:
+      label: Exact install command(s) you ran
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: error
+    attributes:
+      label: Error output
+      description: Paste the full output, including any checksum or SHA verification lines if present.
+      render: shell
+    validations:
+      required: true
+
+  - type: input
+    id: tool_versions
+    attributes:
+      label: Relevant tool versions
+      description: e.g. `node --version`, `bun --version`, `brew --version`, `curl --version`
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: verification
+    attributes:
+      label: Pre-filing checks
+      options:
+        - label: I confirmed the version exists at https://github.com/omerakben/code-oz/releases
+          required: true
+        - label: I read the install caveats in the README and `SECURITY.md`
+          required: true

.github/pull_request_template.md

@@ -0,0 +1,47 @@
+<!--
+Thanks for opening a PR. Please fill in this template so reviewers can move quickly.
+
+If your PR is a small doc fix, typo, or dependency bump, you can delete sections that do not apply — but please keep the test confirmation checkbox.
+-->
+
+## Summary
+
+<!-- One or two sentences. What changes? Why? -->
+
+## Files changed
+
+<!-- Bullet list of the files touched and what each one does. Helps reviewers skim. -->
+
+## Testing
+
+- [ ] `bun test` passes locally (paste the pass/fail/skip count below).
+
+```
+$ bun test
+... pass / ... fail / ... skip
+```
+
+- [ ] Any new behavior change has a RED-first test (per rule 22 in `CLAUDE.md`).
+- [ ] If this touches an HTTP provider adapter, a redaction test is included.
+
+## Cross-model peer review
+
+The project enforces a cross-model peer review discipline for changes that touch the orchestrator spine, the provider contract, the gate machinery, the CLI surface, or the release workflow. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for details.
+
+- [ ] This PR does NOT need cross-model review (doc-only / typo / dep bump that passes existing tests).
+- [ ] This PR DOES need cross-model review. Codex briefing + response linked below.
+
+If the second box is checked, link the briefing and response:
+
+- Briefing: `docs/design/CODEX_BRIEFING_<topic>.md`
+- Response: `docs/design/CODEX_RESPONSE_<topic>_R<n>.md`
+- Verdict: `push` / `fix-first` / `debate-required`
+
+## Breaking changes
+
+- [ ] No breaking changes.
+- [ ] Yes, breaking changes (describe below; user-facing impact must be in the description).
+
+## Related
+
+<!-- Link any related issues, design docs, milestone identifiers, or prior PRs. -->