docs+fixes(selfhost/ci/chat): claude token docs, ui-only CI gating fix, chat-qa test fix

[JSONbored]

Summary

Three fixes, each individually small, bundled here because each was a real blocker discovered while trying to ship the first one (all detailed in Notes):

1. Docs: docs.self-hosting-security.tsx / docs.self-hosting-ai-providers.tsx document the secrets/claude_code_oauth_token.txt file alternative for CLAUDE_CODE_OAUTH_TOKEN (added to docker-compose.yml in feat(selfhost): add claude code token to native Docker secrets #5144). config/examples/gittensory.full.yml / .gittensory.yml.example (mirrored bodies) fix a stale claim that screenshots is a "plain symmetric override" — fix(review): keep screenshots allowlist-bound #4990 made it allowlist-required (force-off only outside the rollout allowlist), same asymmetry as safety/grounding.
2. CI: .github/workflows/ci.yml's validate-code "Build engine package" step only ran on push, or when backend/engine changed — not ui, even though the very next "UI typecheck" step (gated on ui) transitively needs it (apps/gittensory-ui's tsconfig pulls in src/mcp/local-write-tools.ts, which imports @jsonbored/gittensory-engine). Any PR touching only apps/gittensory-ui/** hit TS2307 here on otherwise-correct code — this PR's own first validate-code run did exactly that. Added the missing ui condition.
3. Test fix: test/unit/ai-chat-qa.test.ts's new lane-signal redaction test (fix(chat): redact private lane signals from Q&A #5149) overrode action.why, a field compactChatSignalBundle() never reads — by design, raw action rationale/blockedBy is omitted entirely from the chat grounding bundle, not merely redacted. The override never reached the prompt, so the test asserted on content that could never appear. redactGroundingText and its new PRIVATE_LANE_SIGNAL_PATTERN regex were already correct the whole time (proven by the adjacent pure-function unit test, which passed throughout) — this was a test-only bug, not a privacy regression. Pointed the override at publicSafeSummary, the field that actually flows into the prompt.

Scope

• The PR title follows type(scope): short summary Conventional Commit format.
• Each of the three changes is individually small and coherent; bundled because chore(release): prepare public gittensory launch #2 and feat(scoring): add situational score projections #3 were genuine blockers surfaced while shipping feat(docs): add install site and mcp diagnostics #1 (see Notes for the exact failing runs).
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
• Linked issue — not applicable; owner-authored fixes, not a contributor PR.

Validation

• git diff --check
• npm run typecheck (root)
• npm run ui:typecheck
• npm run ui:lint (found and auto-fixed one pre-existing-pattern Prettier nit in my own new JSX text; zero errors after)
• npx tsx scripts/gittensory-config-lint.ts .gittensory.yml.example and same for config/examples/gittensory.full.yml — both pass (pre-existing, unrelated blockedPaths is retired warning only)
• npm run docs:drift-check
• npm run actionlint (workflow YAML change)
• npx vitest run test/unit/ai-chat-qa.test.ts — all 31 tests pass after the fix
• npm run test:coverage (full) / test:workers / build:mcp / test:mcp-pack / ui:openapi:check / ui:build / npm audit — not run in full locally; relying on this PR's own CI for the full suite since none of these three changes touch src/** production logic (only a workflow file, docs pages, example-config comments, and one test file)

If any required check was skipped, explain why:

• No production src/** logic changed anywhere in this diff (the chat-qa fix is test-only; redactGroundingText itself is untouched). Relying on CI for the full matrix rather than re-running it all locally given the narrow blast radius.

Safety

• No secrets, tokens, or private values exposed.
• Public GitHub text stays sanitized.
• The chat-qa test fix directly concerns a privacy-redaction boundary — confirmed the underlying redactGroundingText/PRIVATE_LANE_SIGNAL_PATTERN logic was already correct and untouched; only the test's fixture override target was wrong. Traced compactChatSignalBundle() line-by-line to confirm why/blockedBy are deliberately never read (only publicSafeSummary, objective, summary, freshnessWarnings are), matching the file's own documented design intent.
• API/OpenAPI/MCP behavior — not applicable.
• UI changes use live API data — not applicable, static docs content only.
• Public docs are part of this PR.

UI Evidence

Text-only docs changes (prose + one troubleshooting-row string) — no layout/visual change, no screenshots. The CI/test files are not user-facing.

Notes

• Companion follow-up to feat(selfhost): add claude code token to native Docker secrets #5144 (secrets migration) and fix(review): keep screenshots allowlist-bound #4990 (screenshot allowlist fix).
• CI-gating bug: this PR's first validate-code run failed with TS2307 — https://github.com/JSONbored/gittensory/actions/runs/29187025975/job/86634920100. Confirmed pre-existing (not caused by this PR's docs diff) by checking main's own push-triggered runs pass validate-code (the push branch of the condition always builds the engine); only a PR touching solely ui-classified paths hits the gap.
• Chat-qa test bug: after the CI fix above, this PR's validate-tests (4) shard still failed — inherited from main, which is currently red for the same reason (confirmed via main's last several push runs, e.g. the run for commit f166c07aa itself). Traced to the test, not the redaction code; fixed here so both this PR and main go green.

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	gittensory-ui	ac58521	Commit Preview URL Branch Preview URL	Jul 12 2026, 09:11 AM

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.34%. Comparing base (f166c07) to head (42b3f6a).
⚠️ Report is 3 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5201      +/-   ##
==========================================
+ Coverage   87.46%   94.34%   +6.88%     
==========================================
  Files         473      473              
  Lines       39966    39966              
  Branches    14570    14570              
==========================================
+ Hits        34955    37705    +2750     
+ Misses       3600     1585    -2015     
+ Partials     1411      676     -735     

Flag	Coverage Δ
shard-1	46.46% <ø> (ø)
shard-2	34.55% <ø> (ø)
shard-3	30.95% <ø> (ø)
shard-4	33.08% <ø> (?)
shard-5	33.69% <ø> (ø)
shard-6	44.86% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.
see 84 files with indirect coverage changes

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[loopover-orb]

Caution

🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥

🛑 Gittensory review result - fixes required

_{Review updated: 2026-07-12 09:20:19 UTC}

5 files · 2 AI reviewers · 1 blocker · readiness 100/100 · CI failing · blocked

🛑 Suggested Action - Manual Review

• No linked issue detected — If this PR is intended to solve an issue, link it explicitly in the PR body.

Review summary
This PR bundles three small, well-scoped changes: adding docs for the secret-file alternative to CLAUDE_CODE_OAUTH_TOKEN, correcting a stale comment about screenshots' force-on asymmetry (matching #4990's actual allowlist-required behavior), and fixing a real CI gating bug where the engine build step didn't run for UI-only changes despite UI typecheck depending on its dist/ output. The CI fix is verifiable and correctly scoped — adding `|| needs.changes.outputs.ui == 'true'` to the existing OR-chain is the right and minimal fix for the described transitive dependency. The docs and comment changes are prose-only and match the referenced secrets/README.md and PR history accurately.

Nits — 6 non-blocking

• No test-path changes accompany the CI workflow fix, though CI YAML conditionals are typically validated by observing an actual run rather than a unit test, so this is likely acceptable here.
• apps/gittensory-ui/src/routes/docs.self-hosting-ai-providers.tsx: the new paragraph duplicates similar phrasing already used in docs.self-hosting-security.tsx's secret-file description; consider a shared FeatureRow/Callout snippet if this pattern grows to a third secret.
• Consider a short inline comment or PR-linked note in ci.yml near the changed line referencing why `ui` was added, similar to the existing comment above it about the `.tsbuildinfo` restore-keys pattern, so future editors don't accidentally scope it back down.
• nit: apps/gittensory-ui/src/routes/docs.self-hosting-ai-providers.tsx:142 still shows `CLAUDE_CODE_OAUTH_TOKEN=` in the fallback-chain example even though the new guidance at line 193 says to leave that variable unset when using `secrets/claude_code_oauth_token.txt`, so the example should comment it out or call out that secret-file users must remove it.
• apps/gittensory-ui/src/routes/docs.self-hosting-ai-providers.tsx:142: Change the fallback-chain snippet to make the two credential paths explicit, for example by replacing `CLAUDE_CODE_OAUTH_TOKEN=` with `# CLAUDE_CODE_OAUTH_TOKEN=<token from claude setup-token> # or use secrets/claude_code_oauth_token.txt`.
• Code changes lack test evidence — Add focused regression tests or explain why existing coverage is sufficient.

Why this is blocked

• No linked issue detected — If this PR is intended to solve an issue, link it explicitly in the PR body.

CI checks failing

• validate
• validate-tests (4)

Signal	Result	Evidence
Code review	❌ 1 blocker	2 reviewers, synthesized
Linked issue	✅ No-issue rationale	PR body explains why no issue is linked.
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (no linked issue context).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 45 registered-repo PR(s), 37 merged, 409 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 45 PR(s), 409 issue(s).
Gate result	❌ Blocking	Repo-configured hard blocker found.
Improvement	⚠️ ℹ️ None detected	risk: low · value: none — No structural-improvement signals were detected for this PR. LLM value judgment: moderate — The CI gating fix resolves a genuine, confirmed-live false-failure for any UI-only PR, and the doc/comment corrections keep operator-facing documentation and config comments accurate with recent behavior changes (#4990, #5144), making this a small but concretely useful maintenance PR.

Review context

• Author: JSONbored
• Role context: owner (maintainer lane)
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: not available
• Official Gittensor activity: 45 PR(s), 409 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Treat this as maintainer-lane context rather than normal contributor-lane activity.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

[BETA] Chat with Gittensory

Ask Gittensory a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

• @gittensory ask <question> answers contribution-quality Q&A with source citations and freshness.
• @gittensory chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @gittensory mention with a real question is routed to the closest matching read-only command automatically -- no exact syntax required.

Full command reference: https://gittensory.aethereal.dev/docs/gittensory-commands

Visual preview

Route	Viewport	Before (production)	After (this PR's preview)	Diff
/docs/self-hosting-ai-providers	desktop			—
/docs/self-hosting-ai-providers	mobile			—
/docs/self-hosting-security	desktop			—
/docs/self-hosting-security	mobile			—

Click any thumbnail to open the full-size screenshot. Before = production · After = this PR's preview deploy.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review