docs(readme,getting-started,commands): surface refinement/triage workflow + webinstaller alternative (#979, #984)

[MScottAdams]

Summary

Pair of adoption-blocker docs touches landing in one PR (#979 + #984). All changes are pure docs -- no script, task, schema, or behavior changes; skills/deft-directive-refinement/SKILL.md (the canonical agent-facing source of truth) intentionally untouched.

Closes

• Closes docs: surface refinement/triage workflow to end users (Phase 0 / cache / ingest) #979 -- docs: surface refinement/triage workflow to end users (Phase 0 / cache / ingest)
• Closes docs(readme): call out https://webinstaller.fly.dev/ as an alternative installer in README #984 -- docs(readme): call out https://webinstaller.fly.dev/ as an alternative installer in README

Changes

README.md -- two new subsections under the Getting Started area:

• Alternative installer (docs(readme): call out https://webinstaller.fly.dev/ as an alternative installer in README #984) -- Alternative installer -- hosted webinstaller callout sitting next to (not below) the existing primary install instructions, linking https://webinstaller.fly.dev/. Trade-off note (hosted convenience vs. local-only install). Webinstaller stays an alternative path, NOT the recommended default.
• Backlog triage (docs: surface refinement/triage workflow to end users (Phase 0 / cache / ingest) #979) -- new ### 5. Backlog triage (working an existing backlog) subsection with the trigger words ("triage", "work the cache", "pre-ingest"), the scoped first-run command (task triage:bootstrap -- --limit 50 --state open), a cross-reference back to fix(scm,tests): eliminate remaining GraphQL-backed scm.py / live SCM smoke bucket drain after #961 #976 / GraphQL bucket discipline, and links into docs/getting-started.md and commands.md.

docs/getting-started.md (#979) -- new ## Working an existing backlog section covering:

• Scoped first populate flag surface (--limit / --state / --batch-size / --delay-ms / --repo).
• The canonical Phase 0 numbered action menu (accept | reject | defer | needs-ac | mark-duplicate plus Discuss / Back).
• The three-tier inventory model in user vocabulary (cache .deft-cache/github-issue/ -> audit log vbrief/.eval/candidates.jsonl -> accepted backlog vbrief/proposed/).
• The rule that writes flow only through task triage:accept (which delegates to task issue:ingest).
• Why this avoids the shared GraphQL bucket drain (REST-backed cache, batched delays, automatic 429 retries via upstream Retry-After, no live gh issue view per decision).

commands.md (#979) -- new ## Backlog triage & cache tasks section surfacing every task triage:* and task cache:* verb with verb-to-outcome descriptions (bootstrap / accept / reject / defer / needs-ac / mark-duplicate / bulk-* / refresh-active / status / history / reset; cache fetch-all / get / invalidate / prune); cross-links back to the getting-started walkthrough.

Vocabulary parity -- all three doc surfaces use vocabulary identical to skills/deft-directive-refinement/SKILL.md Phase 0 so there is no drift between agent-facing and user-facing copy.

vBRIEF lifecycle

• vbrief/pending/2026-05-08-979-...vbrief.json -> vbrief/active/ (status: running) via task vbrief:activate
• vbrief/pending/2026-05-08-984-...vbrief.json -> vbrief/active/ (status: running) via task vbrief:activate

Both vBRIEFs will lifecycle-move to vbrief/completed/ via task scope:complete after Greptile review-cycle exits clean.

Validation

• task check green (4389 passed, 3 skipped, 1 xfailed; 942 files clean per verify:encoding).
• task pr:check-closing-keywords -- --commits-file <commit messages> clean (no closing-keyword negation/quotation/example/code-block hits).

PR Checklist

• Conventional commit subject (docs(readme,getting-started,commands): ...).
• CHANGELOG.md [Unreleased] entry under ### Added (combined entry covering both docs: surface refinement/triage workflow to end users (Phase 0 / cache / ingest) #979 and docs(readme): call out https://webinstaller.fly.dev/ as an alternative installer in README #984).
• Both closing keywords in PR body (Closes #979, Closes #984).
• No file-overlap with other agents in the cohort (per the dispatch envelope's CONSTRAINTS list).
• Vocabulary lines up with skills/deft-directive-refinement/SKILL.md Phase 0.

[greptile-apps]

Greptile Summary

This is a pure-docs PR that closes two adoption-blocker issues: it surfaces the Phase 0 triage/refinement workflow to end users across three coordinated doc surfaces, and adds the hosted webinstaller at webinstaller.fly.dev as a visible alternative installer path in README.md.

• README.md gains two new subsections: an Alternative installer callout for the hosted webinstaller (with trade-off note) and a ### 5. Backlog triage subsection with trigger words, the scoped bootstrap command, and cross-links to the full walkthrough.
• docs/getting-started.md gains a ## Working an existing backlog section covering the flag surface, the numbered action menu, the three-tier inventory model (cache → audit log → accepted backlog), and the REST-backed rationale for avoiding the GraphQL bucket drain.
• commands.md gains a ## Backlog triage & cache tasks section documenting every task triage:* and task cache:* verb; the triage:refresh-active entry was updated from the prior draft to correctly reference gh api repos/<owner>/<repo>/issues/<N> instead of gh issue view --json, addressing the concern raised in review.

Confidence Score: 5/5

Pure documentation change with no script, task, schema, or behavior modifications — safe to merge.

All changed files are Markdown or JSON lifecycle metadata. The three doc surfaces are internally consistent, vocabulary aligns with the canonical skills/deft-directive-refinement/SKILL.md Phase 0, and the triage:refresh-active REST-path concern from the prior review cycle was addressed in this diff. No logic, schema, or executable code was touched.

CHANGELOG.md — a duplicate, truncated gh_rest.py stub was introduced in this diff (noted in a prior review thread); that entry should be cleaned up before the next release cut.

Important Files Changed

Filename	Overview
docs/getting-started.md	Adds comprehensive ## Working an existing backlog section with four numbered steps covering the flag surface, action menu, three-tier inventory model, and GraphQL avoidance rationale. Vocabulary and REST-path references are consistent with the updated commands.md.
commands.md	Adds ## Backlog triage & cache tasks section documenting all task triage:* and task cache:* verbs. Notably, triage:refresh-active now correctly cites gh api repos/<owner>/<repo>/issues/<N> and explicitly notes the preference over gh issue view --json, addressing the concern from the prior review thread.
README.md	Adds alternative installer callout and ### 5. Backlog triage subsection. Content is accurate; trigger words "triage" / "work the cache" / "pre-ingest" are surfaced here but the AGENTS.md Skill Routing table (noted in prior review thread) does not yet map them to the refinement skill.
CHANGELOG.md	Adds a combined entry for #979 and #984. A duplicate, truncated stub for feat(scripts): gh_rest.py was introduced (unclosed bold markup, missing description body) — this was flagged in the prior review thread and remains unresolved in this diff.
vbrief/completed/2026-05-08-979-docs-surface-refinementtriage-workflow-to-end-users-phase-0.vbrief.json	Status lifecycle move from pending → completed; updated timestamp added to vBRIEFInfo and plan blocks. No issues.
vbrief/completed/2026-05-08-984-docsreadme-call-out-httpswebinstallerflydev-as-an-alternativ.vbrief.json	Status lifecycle move from pending → completed; updated timestamps added. No issues.

_{Reviews (4): Last reviewed commit: "chore(vbrief): lifecycle-move #979 + #98..." | Re-trigger Greptile}

[deft-slizard]

SLizard Review — 0 findings across 6 file(s) · confidence 0.29

Unable to provide confident assessment at current analytical confidence (0.29). Manual review recommended.

Files reviewed:

• CHANGELOG.md
• README.md
• commands.md
• docs/getting-started.md
• vbrief/active/2026-05-08-979-docs-surface-refinementtriage-workflow-to-end-users-phase-0.vbrief.json
• vbrief/active/2026-05-08-984-docsreadme-call-out-httpswebinstallerflydev-as-an-alternativ.vbrief.json

⚠️ Confidence gap: This review produced 0 findings at confidence 0.29 (below 0.60). No clean-review rationale was captured — the reviewer cannot confirm whether the clean result reflects genuine absence of issues or insufficient analytical confidence. Manual review is recommended.

Deterministic checks: passed — vBRIEF traceability checks passed.

Review coverage

• Reviewed files: CHANGELOG.md, README.md, commands.md, docs/getting-started.md, vbrief/active/2026-05-08-979-docs-surface-refinementtriage-workflow-to-end-users-phase-0.vbrief.json, vbrief/active/2026-05-08-984-docsreadme-call-out-httpswebinstallerflydev-as-an-alternativ.vbrief.json
• Skipped files: none
• Source: github @ c34929ae1a11

Context used

• Static findings: 2
• Static tools: diff-truncation-check
• Graph/blast radius: 0 changed node(s), 0 affected node(s)
• Vector context chunks: 21
• Context availability: full
• Review categories: default
• Deterministic checks: vbrief-traceability=passed, markdown-fences=passed, unused-exports=passed, query-docstring=passed, xss-sprintf=passed, markdown-xref=passed, aria-target=passed, semantic-role=passed, aria-containment=passed, redundant-assertion=passed, resource-lifecycle=passed, cross-diff-consistency=passed, redundant-css-block=passed, template-placeholder=passed, void-async-signal=passed, spread-override=passed, json-indent-consistency=passed, dep-swap=passed, powershell-scoping=passed, diff-truncation=failed, exception-type-contract=passed, dead-none-guard=passed, access-declaration=passed, unused-option=passed, css-property-interaction=passed, jsx-style-indent=passed, regex-breadth=passed, cartesian-fan-out=passed, exec-stdout-parse=passed, sentinel-error-wiring=passed, hardcoded-filemode=passed, api-response-shape=passed, python-cli-arg=passed, taskfile-namespace=passed, vbrief-schema=passed, go-shell-injection=passed, go-discarded-error=passed, inline-style-proliferation=passed, unnecessary-nonnull-assertion=passed, ssrf-guard-completeness=passed, error-message-leak=passed, puppeteer-resource-cap=passed, trivial-argument=passed, dead-store=passed, phantom-import=passed, fetch-timeout-guard=passed, log-level-expected-path=passed, unified-diff-construction=passed, graph-incompleteness=passed, lockfile-version-suppression=passed
• Degraded context: Decision capped at comment: deterministic check(s) failed (diff-truncation) (issue #458).

Suggested verification

• (agent) Spot-check the highest-risk changed files and confirm the clean review did not skip relevant files or context.
• (static) Review 2 deterministic/static finding(s) included in the evidence set.

Agent verification brief

• PR/CR: deftai/directive#995
• Head SHA: c34929ae1a11a0f61c7e4e76971b7a536af67555
• Decision: comment
• Highest-risk claims: none
• Reviewed files: CHANGELOG.md, README.md, commands.md, docs/getting-started.md, vbrief/active/2026-05-08-979-docs-surface-refinementtriage-workflow-to-end-users-phase-0.vbrief.json, vbrief/active/2026-05-08-984-docsreadme-call-out-httpswebinstallerflydev-as-an-alternativ.vbrief.json
• Skipped files: none
• Evidence sources: static analysis, call graph/blast radius, vector context, deterministic checks
• Known blind spots: Decision capped at comment: deterministic check(s) failed (diff-truncation) (issue #458).

Decision: comment
Merge impact: non-blocking
Review confidence: 0.29
Decision confidence: 0.29
Finding confidence: n/a
Reason: Findings are advisory under the current severity/confidence policy.
Important files: 6 changed file(s) reviewed; no finding hotspots identified.
Review scope: 6 files, 107 additions, 5 deletions

_{slizard v0.3.206}