found-issues

verify

Drive found-issues CLI changes end-to-end — build/launch/drive recipe for verifying bin/found-issues, hooks, and statusline integrations at their real surfaces.

Move old [fixed] entries out of docs/found-issues.md into docs/found-issues-archive.md (keeps the newest 50 or 30 days, whichever threshold hits first). Mutating and one-way — the archive file is append-only and entries do not come back, so use --dry-run to preview. Open and deferred entries are never touched. Use when the [fixed] tail is drowning the ledger, not as routine post-sync cleanup.

fi-defer

Park an [open] entry as [deferred] — it stays in the ledger but leaves the statusline counter, optionally with a reason or mute-until window. Use for known-but-consciously-postponed work, NOT to silence an entry someone should fix (real fixes close via the annotate commands plus sync). Re-deferring after a promotion increments the defer-cycle and escalates the next nudge. Inverse of $fi-promote-deferred.

fi-doctor

Read-only health check of the found-issues installation — CLI version vs installed plugin, statusline wiring, gh auth, mode detection, hook opt-outs, ledger file state. Run when something looks wrong (counter missing, sync not firing, stale CLI after an update) or after install or upgrade. Diagnoses only and changes nothing — follow its printed advice to fix.

fi-promote-deferred

Revive a [deferred] entry back to [open], preserving every annotation (touch history, defer-cycle, reason) as evidence of recurrence. Use when a parked issue starts biting again or its mute window expired. Inverse of $fi-defer. Despite the similar name it is unrelated to $fi-promote, which copies branch-only entries onto the default branch before a branch is deleted.

fi-promote

Copy [open] entries that exist only on the current branch onto the default branch before the branch is deleted — entries logged mid-branch would otherwise die with it. Run before branch cleanup; the pre-branch-delete hook blocks deletion until it has run. Despite the similar name it is unrelated to $fi-promote-deferred, which flips a single [deferred] entry back to [open] in place.

fi-setup

First-run orientation — explains the system, surfaces optional config, offers the statusline integration and the fi alias. Run once after installing; safe to re-run. Logging itself is zero-config and does not need this.

fi-status

Print the current open / in-PR / critical / stale counts as one line. Read-only and safe anytime — use for a quick pulse or when debugging the statusline counter. For the full entry list read docs/found-issues.md directly; for an installation health check use $fi-doctor instead.

fi-uninstall

Wipe plugin-private state — statusline segment, onboarding marker, mode cache, fi alias — BEFORE removing the found-issues plugin itself. The ledger (docs/found-issues.md) is repo data and stays untouched. Run only when actually removing the plugin, not for troubleshooting (that is $fi-doctor).

rules

Rules for how AI agents maintain docs/found-issues.md — logging, annotation after PR/commit, sync, branch-deletion guard, dead code. Auto-loaded every session by the found-issues plugin.