Align Decodex docs and skills with runtime status

README.md

@@ -19,7 +19,8 @@ Repo-native agent orchestration and public Codex signal publishing.
 - Native macOS app for Decodex Codex account-pool management.
 - Explicit project registry under `~/.codex/decodex/projects/<service-id>/`.
 - Local operator listener with a dashboard at `/` and `/dashboard`, WebSocket
-  snapshot/control traffic at `/dashboard/control`, and `GET /livez` for liveness.
+  snapshot/control traffic at `/dashboard/control`, Decodex App snapshot/account
+  APIs under `/api/`, and `GET /livez` for liveness.
 - Static Astro site that publishes GitHub-backed Codex change signals.
 - Deterministic GitHub signal pipeline for change bundles, release deltas, rendered
   signal entries, and content validation.

docs/reference/operator-control-plane.md

@@ -33,6 +33,14 @@ Decodex currently runs as a local, single-machine control plane:
 - The project-owned `WORKFLOW.md` remains the execution-policy contract for that
   registered repo.
 
+Decodex App is a native shell over the same local runtime and account-pool state. On
+launch it connects to an existing default local listener when one is reachable; if
+not, it starts the bundled `decodex` binary as
+`decodex serve --api-only --listen-address 127.0.0.1:8912`. API-only mode serves the
+dashboard, account APIs, and `GET /api/operator-snapshot` for the app, but it does
+not register projects, poll Linear, dispatch work, or accept `--config` or
+`--interval`. Use ordinary `decodex serve --interval ...` for the automation loop.
+
 Project registration is not service intake. The `Projects` dashboard section may show
 multiple enabled projects with visible work at once, and its filter can reveal the full
 registered-project table, but a service is only eligible to intake
@@ -110,10 +118,12 @@ service queue label before treating it as a connector problem.
 The browser dashboard reads the complete published state from the local
 `GET /dashboard/control` WebSocket. That socket is the dashboard authority for
 published snapshots, active-lane activity updates, and local dashboard control
-acknowledgements; there is no separate HTTP snapshot polling route. The current
-browser UI keeps live updates unscoped and exposes explicit stop controls for active
-lanes with a known live child process plus account-pool selection controls; project
-watch, project pause/resume, and manual retry controls are intentionally not shown.
+acknowledgements. `GET /api/operator-snapshot` is the Decodex App read API over the
+same runtime database, not a browser-dashboard polling authority and not a sign that
+an API-only listener owns scheduling. The current browser UI keeps live updates
+unscoped and exposes explicit stop controls for active lanes with a known live child
+process plus account-pool selection controls; project watch, project pause/resume,
+and manual retry controls are intentionally not shown.
 The stop control signals the recorded child process for that run, marks the local
 attempt interrupted, and releases the local queue lease. `ack` is dashboard-local
 acknowledgement only. The socket is not a browser connection to Codex app-server,

docs/runbook/self-dogfood-pilot.md

@@ -366,6 +366,13 @@ wants to observe the self-bootstrap loop without reading source code.
    `app_server_preflight_failed` evidence for the `plugin/list` timeout, restart
    `decodex serve` if the app-server process is stale, and run `decodex probe` until
    plugin inventory responds before clearing `decodex:needs-attention`.
+   If preflight evidence shows `skills/list` enabled skills with scan diagnostics,
+   keep the diagnostics as compatibility evidence and do not uninstall official skills
+   solely to clear the scan error. Only missing cwd coverage or zero enabled skills are
+   `skills/list` blockers; for those, inspect `first_error_path` and `first_error`,
+   update the local Codex/Decodex compatibility or skill metadata as needed, restart
+   `decodex serve`, and rerun `decodex probe` before clearing
+   `decodex:needs-attention`.
 
 4. In Linear, choose two or three small `decodex` issues for the demo batch. Keep each
    issue in a startable state such as `Todo`, make sure it does not carry
@@ -768,6 +775,11 @@ repo gate commands. Linear should carry only the coarse team-visible failure sum
   worktree's local preflight evidence for `plugin/list`, restart `decodex serve` if
   stale, verify `decodex probe`, then clear `decodex:needs-attention` and move the
   issue back to a startable state only when another automated run is desired.
+- If status or Linear terminal failure includes a `skills/list` preflight blocker,
+  inspect the attached `first_error_path` and `first_error` details before changing
+  local plugins or skills. Scan diagnostics with enabled skills are not blockers by
+  themselves; missing cwd coverage or zero enabled skills require local
+  Codex/Decodex compatibility repair before requeueing.
 - If `status` reports retained partial progress or the dashboard shows `Partial patch held`, inspect the named worktree first. Treat the retained patch as local recovery evidence: finish the repo gate and PR handoff if the patch is useful, or reset the worktree before clearing `decodex:needs-attention`.
 - If the run moved back to `Todo` with `decodex:needs-attention`, inspect the worktree, fix the blocking problem, clear `decodex:needs-attention`, and then move the issue back into a startable state for another automated attempt.
 - If the issue should never be automated again, add `decodex:manual-only`.

plugins/decodex/skills/automation/SKILL.md

@@ -52,6 +52,9 @@ wants to register that project and start the scheduler in one command.
 Use `decodex run <ISSUE>` or `cargo run -p decodex --bin decodex -- run <ISSUE>` only
 for a deliberate one-issue automation pass; it still uses the same retained-lane
 eligibility and lifecycle rules.
+Do not use hidden `serve --api-only` for automation. That mode belongs to Decodex App:
+it serves local dashboard/account/app snapshot APIs, but it does not register
+projects, poll Linear, or dispatch lanes.
 
 ## Intake and Ownership
 
@@ -78,6 +81,11 @@ terminal automation signal.
   wait, retained repair, closeout, recovery worktrees, and cleanup debt.
 - Treat runtime DB rows, app-server protocol activity, and Linear execution-ledger
   comments as different evidence surfaces.
+- When app-server preflight mentions `skills/list`, distinguish non-blocking scan
+  diagnostics from real blockers. If the run cwd is present and at least one skill is
+  enabled, preserve `error_count`, `first_error_path`, and `first_error` as evidence
+  but do not stop the lane solely because unrelated installed skill metadata failed to
+  scan. Missing cwd coverage or zero enabled skills remain blockers.
 - Before assuming a lane is stuck, compare lane phase, wait reason, last run activity,
   protocol activity, active lease state, and child-agent activity when present.
 

plugins/decodex/skills/manual-cli/SKILL.md

@@ -80,6 +80,13 @@ Manual commit and landing are separate narrow workflows:
 - Use `run --dry-run` before live automation to validate project loading, issue
   discovery, eligibility, and worktree planning without tracker mutation.
 - Use `probe stdio://` before relying on the Codex app-server boundary.
+- Treat hidden `serve --api-only` as Decodex App infrastructure only. It serves
+  dashboard, account, and app snapshot APIs, but it does not register projects, poll
+  Linear, or dispatch work.
+- For `skills/list` app-server preflight output, enabled skills plus scan diagnostics
+  are local evidence, not a lane blocker. Missing cwd coverage or zero enabled skills
+  are blockers; inspect `first_error_path` and `first_error` before changing plugin or
+  skill installs.
 
 ## Boundaries