---
name: devhub-control
description: Safely transport explicit reads and mutations through the local XA DevHub localhost API. Use when a DevHub workflow skill must inspect health, projects, work, knowledge, workflows, reports, or feedback, or verify a DevHub write. Never edit devhub.db directly, regardless of process state.
---

# DevHub Control

Use `scripts/devhub.ps1` as the single transport for DevHub. Keep model reasoning in the calling skill and keep database invariants in DevHub itself.

## Role boundary

Keep this skill transport-only. Normal development, knowledge, report, release, and copied-packet workflows should target `$devhub-development`, `$devhub-knowledge`, or `$devhub-reports`; those skills call this one. Do not choose project direction, reinterpret payloads, or duplicate higher-level lifecycle rules here.

## Safety contract

1. Call `health` before any sequence of operations.
2. Read the target record before changing it.
3. Use `-WhatIf` when the requested target or payload is ambiguous.
4. Mutate only through the authenticated canonical loopback origin, which defaults to `http://127.0.0.1:21100`; never open or write `devhub.db` directly, regardless of process state. The transport canonicalizes the selected loopback origin and reads its current per-run bearer from the exact-instance JSON rendezvous under the current user's non-roaming LocalAppData. `-TokenPath`, `DEVHUB_TOKEN_PATH`, or `token_path` in `scripts/devhub.config.json` may select an explicit safe rendezvous; the adjacent `data\api-token` lookup remains only as a temporary compatibility path for an already-deployed v1.0.5 process on the default port. It validates schema, origin, live process identity, and token shape, then sends `X-DevHub-Token` on every request. Never print, copy, persist elsewhere, or return that token.
5. Read back every mutation through its direct record or owning aggregate route and report the returned ID or error. The wrapper performs these readbacks automatically. A standalone `source-save` has no read route, so its response is explicitly provisional until the source is attached and verified through the owning knowledge node. `report-context` is verified by the server-emitted registered-capture packet and later exact approval-key consumption.
6. Archive or supersede durable records. Do not invent deletion endpoints.
7. Never return saved Discord tokens or other settings secrets in a report.

## Run commands

```powershell
$dh = Join-Path '<devhub-control-skill-directory>' 'scripts\devhub.ps1'
powershell -NoProfile -ExecutionPolicy Bypass -File $dh -Action health
powershell -NoProfile -ExecutionPolicy Bypass -File $dh -Action project-list
powershell -NoProfile -ExecutionPolicy Bypass -File $dh -Action project-get -Id 1
powershell -NoProfile -ExecutionPolicy Bypass -File $dh -Action work-list -ProjectId 1
powershell -NoProfile -ExecutionPolicy Bypass -File $dh -Action knowledge-context -ProjectId 1 -Query 'current blockers'
powershell -NoProfile -ExecutionPolicy Bypass -File $dh -Action report-context -ProjectId 1 -Kind weekly
powershell -NoProfile -ExecutionPolicy Bypass -File $dh -Action workflow-resume -ProjectId 1
```

For mutations, pass a JSON file or inline JSON through `-InputJson`:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File $dh -Action knowledge-save -InputJson .\node.json -WhatIf
powershell -NoProfile -ExecutionPolicy Bypass -File $dh -Action knowledge-save -InputJson .\node.json
powershell -NoProfile -ExecutionPolicy Bypass -File $dh -Action project-save -InputJson .\project.json -WhatIf
powershell -NoProfile -ExecutionPolicy Bypass -File $dh -Action project-save -Id 1 -InputJson .\project.json
powershell -NoProfile -ExecutionPolicy Bypass -File $dh -Action work-save -InputJson .\ticket.json -WhatIf
powershell -NoProfile -ExecutionPolicy Bypass -File $dh -Action work-save -InputJson .\ticket.json
powershell -NoProfile -ExecutionPolicy Bypass -File $dh -Action work-title -Id 130 -InputJson .\title.json -WhatIf
powershell -NoProfile -ExecutionPolicy Bypass -File $dh -Action work-title -Id 130 -InputJson .\title.json
powershell -NoProfile -ExecutionPolicy Bypass -File $dh -Action work-merge -Id 120 -InputJson .\merge.json -WhatIf
powershell -NoProfile -ExecutionPolicy Bypass -File $dh -Action work-merge -Id 120 -InputJson .\merge.json
powershell -NoProfile -ExecutionPolicy Bypass -File $dh -Action report-status -Id 12 -Status approved
```

`work-title` and `work-merge` are optimistic-concurrency operations: their JSON must carry the exact `updated_at` values returned by the wrapper's prior `work-get` review. The wrapper pre-reads every affected ticket, rejects drift, and directly verifies the title-only or canonical merged result.

Read [references/api-contract.md](references/api-contract.md) for actions, payloads, and response rules. If DevHub is unavailable, stop the DevHub operation and report the health failure; do not fall back to direct database access or silently fabricate a successful write.