chore: governance templates + ARCHITECTURE.md + Phase 3 API docs

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,91 @@
+name: Bug report
+description: Something isn't working as expected
+title: "[Bug] "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug. Please fill in as much detail as you can.
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: A clear and concise description of what the bug is.
+      placeholder: When I do X, Y happens instead of Z.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: Minimal sequence to reproduce the issue.
+      placeholder: |
+        1. Open `/chat`
+        2. Click 'Project' mode
+        3. Type "..."
+        4. See error
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What you expected to happen.
+    validations:
+      required: false
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant logs / audit entries
+      description: |
+        Paste relevant lines from `~/.codec/audit.log` or `pm2 logs codec-dashboard --lines 50 --nostream`.
+        Strip any sensitive data (paths, account names, tokens).
+      render: shell
+    validations:
+      required: false
+  - type: input
+    id: codec-version
+    attributes:
+      label: CODEC version / commit
+      description: Output of `git -C ~/codec-repo rev-parse --short HEAD` and `python3.13 --version`.
+      placeholder: "abc1234, Python 3.13.x"
+    validations:
+      required: false
+  - type: dropdown
+    id: pm2-services
+    attributes:
+      label: Which PM2 service is involved?
+      multiple: true
+      options:
+        - codec-dashboard
+        - codec-agent-runner
+        - codec-observer
+        - codec-mcp-http
+        - codec-heartbeat
+        - codec-hotkey
+        - codec-dictate
+        - open-codec
+        - codec-imessage
+        - codec-telegram
+        - codec-watchdog
+        - codec-overlay
+        - none / not applicable
+    validations:
+      required: false
+  - type: input
+    id: macos-version
+    attributes:
+      label: macOS version
+      placeholder: "14.5 (Sonoma) on M1 Ultra"
+    validations:
+      required: false
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Pre-flight check
+      options:
+        - label: I searched existing issues and discussions to confirm this isn't already reported
+          required: true
+        - label: I confirmed the issue happens with all default kill switches enabled (`AGENT_*`, `OBSERVER_*`, `TRIGGERS_*`, etc.)
+          required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Discussion / Q&A / "is this a bug?"
+    url: https://github.com/AVADSA25/codec/discussions
+    about: For open-ended questions, setup help, or "I'm not sure if this is a bug yet" — use Discussions instead of opening an issue.
+  - name: Enterprise setup
+    url: https://avadigital.ai
+    about: Custom integration, deployment across a team, or paid setup work.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,64 @@
+name: Feature request
+description: Suggest a new skill, capability, or improvement
+title: "[Feature] "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the suggestion. CODEC's design is opinionated — we keep things small, local-first, and reversible. The clearer your description, the easier it is to scope.
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: Describe the user pain or workflow gap, not the solution.
+      placeholder: "Right now I have to manually X every time I Y. It takes 5 minutes and I do it 10x/day."
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: What should CODEC do? If it's a new skill, describe the trigger phrase + output. If it's a UI change, describe where it goes.
+    validations:
+      required: true
+  - type: dropdown
+    id: category
+    attributes:
+      label: Which area?
+      options:
+        - New skill (drop-in `skills/*.py`)
+        - Existing skill enhancement
+        - PWA / dashboard UI
+        - Voice / wake-word path
+        - MCP integration (claude.ai, Cursor, etc.)
+        - Agent system (Phase 3 plan-and-build)
+        - Memory / search
+        - Notifications / alerts
+        - Documentation
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Any workarounds you tried? Other tools that solve this differently?
+    validations:
+      required: false
+  - type: textarea
+    id: scope
+    attributes:
+      label: Scope guess
+      description: How big is this? 1-line config flag, new skill (~100 LOC), or new module?
+    validations:
+      required: false
+  - type: checkboxes
+    id: privacy
+    attributes:
+      label: Privacy alignment
+      options:
+        - label: This proposal works locally (no required cloud dependency for the core feature)
+          required: false
+        - label: This proposal respects the local-first principle (no automatic data exfiltration)
+          required: false

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,52 @@
+<!--
+Thanks for contributing to Sovereign AI Workstation / CODEC.
+Fill the relevant sections; delete the rest.
+-->
+
+## Summary
+
+<!-- One-paragraph description of what this PR does and why. -->
+
+## Reference
+
+<!-- Link to: relevant docs/PHASE*-*.md design or plan, related issue, prior PR -->
+
+## What changes
+
+| Path | Type | Purpose |
+|---|---|---|
+| `path/to/file.py` | NEW \| MOD | what this file is responsible for |
+
+<!-- Repeat per file. Skip if changes are obvious from the diff. -->
+
+## Test plan
+
+- [ ] 🧪 New tests added (file: `tests/test_*.py`)
+- [ ] 🧪 Full pytest passes — same baseline 20 failed / 73 skipped, only new passing tests added
+- [ ] All new audit events emit with correct `correlation_id` per Step 1 §1.4 envelope contract
+- [ ] No writes to `~/.codec/*` from tests (verify `temp_codec_dir` fixture covers `codec_audit._AUDIT_LOG`)
+- [ ] All kill switches still work (env var disables the feature)
+
+**Manual smoke test after merge:**
+- [ ] `git pull && pm2 restart <service>`
+- [ ] [describe the user-facing test sequence here]
+
+## Audit emits added
+
+<!-- List any new audit event names + frozenset addition. Skip if none. -->
+
+## Kill switches added or modified
+
+<!-- List any new env vars / config flags. Skip if none. -->
+
+## Out of scope (explicitly deferred)
+
+<!-- What this PR does NOT do, with rationale. Helps reviewer scope expectations. -->
+
+## Self-review checklist
+
+- [ ] Read every line of the diff myself
+- [ ] No commented-out code, no `print()` left in
+- [ ] No emojis added to code/files unless explicitly requested by the user
+- [ ] No `~/.codec/*` paths hand-written that should go through atomic R/W helpers
+- [ ] Followed existing patterns; didn't refactor unrelated code

docs/API.md

@@ -140,6 +140,115 @@ List saved custom agents.
 
 ---
 
+## Autonomous Agents (Phase 3 — drop-a-project mode)
+
+The agent system added in Phase 3. User drops a project description; Qwen-3.6 drafts a structured plan with explicit permission manifest; user approves once; `codec-agent-runner` PM2 daemon executes autonomously with permission gate enforcement, tamper detection, and resume-after-restart.
+
+For full design, see `docs/PHASE3-BLUEPRINT.md`. For runtime architecture, see `docs/ARCHITECTURE.md` (Phase 3 sequence diagram).
+
+### POST /api/agents
+Create a new agent and draft its plan via Qwen-3.6 (typical 2–10 s).
+
+```bash
+curl -X POST -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"title":"Marbella property bot","description":"Build a Telegram bot that monitors Marbella property listings under €500k and pings me on new ones"}' \
+  http://localhost:8090/api/agents
+# → {"agent_id": "agent_abc123", "status": "awaiting_approval"}
+```
+
+### GET /api/agents
+List all agents with current status. Polled by the PWA every 5 s for the agent status pills above the chat input.
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" http://localhost:8090/api/agents
+# → {"agents": [{"agent_id":"...","title":"...","status":"running","created_at":"..."}]}
+```
+
+### GET /api/agents/{id}
+Full agent state — manifest + plan + state + grants in one response. The PWA's "View plan" button calls this.
+
+### POST /api/agents/{id}/approve
+Approve drafted plan. Re-validates skills against registry, computes plan_hash (sha256), writes grants.json, transitions `awaiting_approval → approved`. The daemon picks up `approved` agents within 5 s.
+
+### POST /api/agents/{id}/reject
+Body: `{"reason": "..."}` (optional). Transitions to `rejected`; plan dir kept 7 days for review then auto-deleted.
+
+### POST /api/agents/{id}/revise
+Body: `{"edited_plan": { ... full Plan dict ... }}`. User-edited plan, re-validated, transitions `awaiting_approval → revised → awaiting_approval`.
+
+### POST /api/agents/{id}/abort
+Atomic transition to `aborted`. Daemon checks status before each operation.
+
+### POST /api/agents/{id}/pause / /resume
+`paused → running` (resume), or `running → paused` (pause). Idempotent.
+
+### POST /api/agents/{id}/grant
+Grant a missing permission to a `blocked_on_permission` agent. Per-agent only (not global).
+
+```bash
+curl -X POST -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"kind":"skills","value":"calculator"}' \
+  http://localhost:8090/api/agents/agent_abc123/grant
+```
+
+`kind` ∈ `skills` / `read_paths` / `write_paths` / `network_domains`.
+
+### POST /api/agents/{id}/extend_budget
+Bump current checkpoint's step_budget. Only valid when `status=paused` AND `status_reason=step_budget_exhausted`.
+
+```bash
+curl -X POST -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"additional_steps":20}' \
+  http://localhost:8090/api/agents/agent_abc123/extend_budget
+```
+
+Returns `{previous_budget, new_budget, status:"running"}`. Override is written to `state.json` (plan stays immutable; tamper-hash check intact).
+
+### GET /api/agents/{id}/messages
+Return the full message timeline from `~/.codec/agents/{id}/messages.jsonl`.
+
+```json
+{"messages":[
+  {"ts":"2026-05-03T12:15:00Z","type":"agent_update","title":"Checkpoint 2/5: Scaffolded bot","body":"...","actions":[...]}
+]}
+```
+
+`type` ∈ `agent_update` / `agent_blocked` / `agent_question` / `agent_done` / `agent_aborted` / `user_reply`.
+
+### POST /api/agents/{id}/messages
+User reply — daemon picks up between checkpoints.
+
+```bash
+curl -X POST -H "Authorization: Bearer $TOKEN" \
+  -d '{"body":"please skip the email step and continue"}' \
+  http://localhost:8090/api/agents/agent_abc123/messages
+```
+
+### POST /api/agents/{id}/silence
+Toggle banner silence per-agent. Silenced = timeline messages still written; notifications.json banner skipped (no badge spam).
+
+```bash
+curl -X POST -d '{"silenced":true}' http://localhost:8090/api/agents/agent_abc123/silence
+```
+
+### Global allowlist (cross-agent permissions, Q4)
+
+#### GET /api/agent_global_grants
+Read the global allowlist.
+
+#### POST /api/agent_global_grants
+Add an entry. Body: `{"kind":"network_domains","value":"github.com"}`. Items added here are auto-approved on every future plan.
+
+#### DELETE /api/agent_global_grants
+Remove an entry. Same body shape.
+
+`kind` ∈ `network_domains` / `read_paths` / `write_paths` / `skills`.
+
+---
+
 ## Schedules
 
 ### GET /api/schedules