docs: live-queryable Dockhand state + dockhand-api skill #5

Merged

adam merged 2 commits from dockhand-api-skill into main

2026-07-11 17:53:58 -05:00

adam commented

2026-07-11 15:48:50 -05:00

Owner

Corrects the repo docs to match what the Dockhand API actually reports, and adds a skill so agents introspect live state instead of trusting a static list.

Why

Audited the live Dockhand API (:8647) while wiring DroppedNeedle and found the static CLAUDE.md stack table was materially wrong:

arr / media / ai / data / search are NOT Dockhand-managed — legacy Unraid template containers; editing their compose has no deploy effect.
hindsight + 1password-connect still track the stale GitHub repo (repo id 1), not Forgejo — the migration is half-done.
Only proxy truly auto-deploys on push — autoUpdate is off everywhere; webhooks are per-stack and only proxy has one wired (duplicated x2). auth has the Dockhand flag on but no Forgejo hook.

Changes

CLAUDE.md: replace the drift-prone stack table with a live-query pointer + the durable facts the API won't state plainly (infra bootstrap paradox, the two-repo split, the auto-deploy reality).
.claude/skills/dockhand-api/SKILL.md: new introspection-first skill — Bearer auth via op://foundry/dockhand/api_key, the ?env=1 gotcha, git-stack/repo endpoints, drift-check recipe, Hermes headless pattern, and writes flagged break-glass.
.claude/skills/README.md: register the skill; fix the cross-cutting ground rule that repeated the auto-deploy myth.

Memory files (outside the repo) updated to point at the skill as source of truth.

Note for reviewer

Local main had an unpushed commit 0fe725d (lab review) and was missing origin's printing PR #3 — I based this branch on origin/main so it contains only the docs change. Your local main still has 0fe725d; worth pushing or dropping it deliberately.

🤖 Generated with Claude Code

Corrects the repo docs to match what the Dockhand API actually reports, and adds a skill so agents introspect live state instead of trusting a static list. ## Why Audited the live Dockhand API (`:8647`) while wiring DroppedNeedle and found the static `CLAUDE.md` stack table was materially wrong: - **arr / media / ai / data / search are NOT Dockhand-managed** — legacy Unraid template containers; editing their compose has no deploy effect. - **hindsight + 1password-connect still track the stale GitHub repo** (repo id 1), not Forgejo — the migration is half-done. - **Only `proxy` truly auto-deploys on push** — `autoUpdate` is off everywhere; webhooks are per-stack and only proxy has one wired (duplicated x2). `auth` has the Dockhand flag on but no Forgejo hook. ## Changes - `CLAUDE.md`: replace the drift-prone stack table with a **live-query pointer** + the durable facts the API won't state plainly (infra bootstrap paradox, the two-repo split, the auto-deploy reality). - `.claude/skills/dockhand-api/SKILL.md`: new introspection-first skill — Bearer auth via `op://foundry/dockhand/api_key`, the `?env=1` gotcha, git-stack/repo endpoints, drift-check recipe, Hermes headless pattern, and writes flagged break-glass. - `.claude/skills/README.md`: register the skill; fix the cross-cutting ground rule that repeated the auto-deploy myth. Memory files (outside the repo) updated to point at the skill as source of truth. ## Note for reviewer Local `main` had an unpushed commit `0fe725d` (lab review) and was missing origin's printing PR #3 — I based this branch on `origin/main` so it contains only the docs change. Your local `main` still has `0fe725d`; worth pushing or dropping it deliberately. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

adam added 1 commit

2026-07-11 15:48:51 -05:00

docs: make Dockhand state live-queryable, add dockhand-api skill 16ecb41b80

Replaces the drift-prone static stack table in CLAUDE.md with a live-query
pointer, and adds a dockhand-api skill (introspection-first, writes gated).
Corrects three myths the static docs hid, all verified against the live API:
legacy arr/media/etc. stacks are not Dockhand-managed; hindsight and
1password-connect still track the stale GitHub repo; only proxy truly
auto-deploys on push.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

adam added 1 commit

2026-07-11 17:41:07 -05:00

docs: reflect completed GitHub→Forgejo migration + repo immutability 99e74159f1

Tasks 1 & 2 executed against the live Dockhand API: droppedneedle git-stack
registered (id 11, webhook wired), and hindsight + 1password-connect migrated
off the stale GitHub mirror by repointing repo record 1 to Forgejo (a
git-stack's repositoryId is immutable on update, so the shared repo record
was edited instead). All foundry stacks now track Forgejo.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

adam force-pushed dockhand-api-skill from 99e74159f1 to 4049bfa508

2026-07-11 17:53:44 -05:00

Compare

adam merged commit 3851c6cfb9 into main

2026-07-11 17:53:58 -05:00

adam referenced this pull request from a commit

2026-07-11 17:53:59 -05:00

docs: live-queryable Dockhand state + dockhand-api skill (#5)