feat(docs): generate Section 5 from function comment headers
The man-page-style comment header above each function in functions/*.fish becomes the SSOT for that function's documentation. Writing a new function and documenting it are now the same act. - manualtools.parse_functions() parses every header carrying a # CATEGORY; absence of one is the opt-in, keeping bundled-plugin and prompt internals out of the manual with no exclusion list to maintain. - build-manual.py generates entries for both --concat and --site, with **Dependencies:** rendered as links and a **Used by:** reverse index computed in one pass. Cross-category links are the navigation win. - docs/manual/05-functions/*.md reduced to frontmatter-only stubs. Every intro measured zero words, so the category files were pure entry containers; ordering, titles, and helpKeywords routing are untouched. - _first_sentence() unwraps the leading hard-wrapped paragraph and skips the whole Synopsis block, not just its label line. Site cards no longer truncate mid-clause or show a synopsis as their description. Verification, per the design spec: - test_concat_roundtrips_original scoped to sections 0-4 and 6-11. It guarded a format migration; this is a content migration. - replaced by structural checks: one entry per categorised function, the required sections present, every category resolving to a stub with no stub empty, and every declared dependency resolving to a real function or a type -q-guarded binary. - public functions lacking # CATEGORY warn rather than fail, so a new user-facing function going undocumented stays visible in CI. 24/24 checks pass. 94 entries generated from 94 parsed headers. Also drops a stale claim from open-url's NOTES: config-help --html calls xdg-open directly and has never called open-url.
This commit is contained in:
@@ -7,110 +7,4 @@ helpKeywords:
|
||||
- ai
|
||||
---
|
||||
|
||||
## agy
|
||||
|
||||
Synopsis: agy [args...]
|
||||
Wrapper for the agy Antigravity AI CLI. Before launching, delegates to
|
||||
agents-init --agents to ensure AGENTS/ is scaffolded and CLAUDE.md is
|
||||
symlinked to AGENTS/AGENTS.md in the current project, then forwards all
|
||||
arguments verbatim to the real agy binary. Command shadow (C1): when
|
||||
__fish_config_op_aliases (or the master) is disabled, the call is
|
||||
passed through to the real agy binary unchanged.
|
||||
|
||||
agy chat
|
||||
agy resume
|
||||
|
||||
## antigravity-ide
|
||||
|
||||
Synopsis: antigravity-ide [args...]
|
||||
Runs the antigravity-ide editor with warnings filtered.
|
||||
|
||||
## agents-init
|
||||
|
||||
Synopsis: agents-init [--agents | --plugins]
|
||||
Scaffold an AGENTS/ sub-repository for tracking agent specs, plans, specs,
|
||||
and dev logs. Creates AGENTS/ as a standalone git repo, moves any existing
|
||||
AGENTS.md into it, and replaces it with a relative symlink (plus
|
||||
CLAUDE.md -> AGENTS/AGENTS.md so Claude Code picks up the shared agent
|
||||
instructions). Consolidates plans/ and specs/ directly under AGENTS/
|
||||
(merging any legacy docs/plans, docs/superpowers/plans, or old
|
||||
AGENTS/plugins/ locations into the canonical AGENTS/<tgt>), creates
|
||||
AGENTS/devlogs/, and wires docs/superpowers/{plans,specs} symlinks back to
|
||||
them. Adds managed paths to .gitignore and auto-commits every change inside
|
||||
the AGENTS/ sub-repo; pulls first when the sub-repo has an upstream.
|
||||
Fully idempotent: a second run produces no output and no new commits.
|
||||
Flags: --agents re-runs only the AGENTS.md / symlink step; --plugins
|
||||
re-runs only the plans/specs/devlogs wiring step. Called automatically by
|
||||
the claude and agy wrappers on every invocation.
|
||||
|
||||
Structure versioning: each AGENTS/ repo carries a self-contained version
|
||||
bumper. AGENTS/.version holds MAJOR.MINOR.PATCH (seeded 1.0.0). Committed
|
||||
git hooks under AGENTS/.agents-tools/ (wired via core.hooksPath) bump it on
|
||||
every commit: MINOR (resetting PATCH) when the tracked directory set
|
||||
changes, PATCH otherwise; MAJOR is manual-only. A prepare-commit-msg hook
|
||||
appends "(vX.Y.Z)" to the commit subject. Downstream tooling can read
|
||||
AGENTS/.version - a changed MINOR field signals a structure change. Because
|
||||
core.hooksPath is a single setting, the local override would otherwise
|
||||
shadow your global hooks; after bumping the version, each shim chains
|
||||
(execs) to the global/system core.hooksPath hook of the same name so global
|
||||
pre-commit / prepare-commit-msg hooks (e.g. ggshield, Git LFS) still run.
|
||||
The script and hooks are shipped from scripts/agents-tools/ and refreshed
|
||||
when their version marker is stale.
|
||||
|
||||
agents-init
|
||||
agents-init --agents
|
||||
agents-init --plugins
|
||||
|
||||
## claude
|
||||
|
||||
Synopsis: claude [args...]
|
||||
Wrapper for the claude CLI. Before launching, delegates to agents-init
|
||||
--agents to ensure AGENTS/ is scaffolded and CLAUDE.md is symlinked to
|
||||
AGENTS/AGENTS.md in the current project, then forwards all arguments
|
||||
verbatim to the real claude binary. Command shadow (C1): when
|
||||
__fish_config_op_aliases (or the master) is disabled, the call is
|
||||
passed through to the real claude binary unchanged.
|
||||
|
||||
claude
|
||||
claude --resume
|
||||
|
||||
## claude-docs
|
||||
|
||||
Synopsis: claude-docs
|
||||
Invokes Claude Code to analyze recent repository changes and update
|
||||
README.md, ensuring all documented features and examples are accurate.
|
||||
|
||||
## claude-pr
|
||||
|
||||
Synopsis: claude-pr
|
||||
Invokes Claude Code to run the full PR workflow: create branch,
|
||||
conventional commit, verification, push, and open a PR with a manual
|
||||
verification checklist.
|
||||
|
||||
## qc
|
||||
|
||||
Synopsis: qc [prompt...]
|
||||
Quick-chat wrapper around the aichat LLM CLI that defaults to the "cli"
|
||||
role - a system prompt tuned for concise, terminal-friendly output. On
|
||||
first use it installs the bundled role by symlinking
|
||||
scripts/cli-agent.md to $XDG_CONFIG_HOME/aichat/roles/cli.md (creating
|
||||
the directory if needed). Inherits every aichat flag and tab completion
|
||||
(--wraps aichat); passing --role/-r overrides the default role, so qc
|
||||
forwards to aichat unchanged. The function is only defined when aichat
|
||||
is installed. Run qc --help for aichat's full flag reference with the
|
||||
command name rewritten to qc.
|
||||
|
||||
qc "how do I list open ports on linux?"
|
||||
qc -m ollama:llama3 "explain this error"
|
||||
qc --role coder "refactor this function"
|
||||
|
||||
## superpowers
|
||||
|
||||
Synopsis: superpowers [on|off] [-g]
|
||||
Enables or disables the Superpowers plugin for Antigravity and Claude
|
||||
Code at workspace/project scope (default) or user scope (-g/--global).
|
||||
|
||||
superpowers on
|
||||
superpowers off -g
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user