coilyco-flight-deck/cli-guard
1
0
Fork 0
Code Issues 12 Pull requests Projects Releases Packages Wiki Activity Actions

Decide gen-webdocs fate now that cli-web-docs is archived #24

New issue
Open
opened 2026-05-28 00:59:40 +00:00 by coilysiren · 0 comments
coilysiren commented 2026-05-28 00:59:40 +00:00
Owner
Copy link

Problem — scripts/gen-webdocs/main.go imports github.com/coilysiren/cli-web-docs to render a static HTML CLI reference for every example under site/cli/<example>/, published at coilysiren.github.io/cli-guard/cli/. cli-web-docs is archived per agentic-os-kai#365. Go modules don't care about GH archive state, so the script keeps building, but the dependency now points at a frozen upstream.

Options

  1. Keep-frozen (default-safe, lowest cost). Leave the import as-is. cli-web-docs stays archived, gen-webdocs keeps using the last released version. Risk: any future urfave/cli v3 change that breaks the renderer's CLI-tree introspection has no upstream fix path. Cost if it breaks later: small one-time replacement.
  2. Delete the script and the published docs site. Drop scripts/gen-webdocs/, drop the gen-webdocs verb from .agent-guard/agent-guard.yaml, drop the coilysiren.github.io/cli-guard/cli/ deploy. README's "CLI reference" link goes away. Lightest long-term tail. Reasonable if the published site sees no traffic.
  3. Inline renderer. Move the small subset of cli-web-docs the script actually uses into scripts/gen-webdocs/ directly. No external dep. Costs an afternoon. Worth it only if the published site is load-bearing for cli-guard's discoverability.

Recommendation

Default to (1) unless the site has known external readers. If killing the site is on the table at all, (2) beats (3): the inline renderer adds maintenance surface that has to keep pace with goldmark + urfave/cli-docs.

Action

  • Pick an option.
  • For (1): close this issue with a short comment noting "keep-frozen, will revisit if it breaks."
  • For (2) or (3): land the code change, close on commit.

Prior art

  • agentic-os-kai#365 - archive of cli-web-docs (parent decision)
**Problem** — `scripts/gen-webdocs/main.go` imports `github.com/coilysiren/cli-web-docs` to render a static HTML CLI reference for every example under `site/cli/<example>/`, published at `coilysiren.github.io/cli-guard/cli/`. cli-web-docs is archived per agentic-os-kai#365. Go modules don't care about GH archive state, so the script keeps building, but the dependency now points at a frozen upstream. ## Options 1. **Keep-frozen** (default-safe, lowest cost). Leave the import as-is. cli-web-docs stays archived, gen-webdocs keeps using the last released version. Risk: any future urfave/cli v3 change that breaks the renderer's CLI-tree introspection has no upstream fix path. Cost if it breaks later: small one-time replacement. 2. **Delete the script and the published docs site.** Drop `scripts/gen-webdocs/`, drop the `gen-webdocs` verb from `.agent-guard/agent-guard.yaml`, drop the `coilysiren.github.io/cli-guard/cli/` deploy. README's "[CLI reference](https://coilysiren.github.io/cli-guard/cli/)" link goes away. Lightest long-term tail. Reasonable if the published site sees no traffic. 3. **Inline renderer.** Move the small subset of cli-web-docs the script actually uses into `scripts/gen-webdocs/` directly. No external dep. Costs an afternoon. Worth it only if the published site is load-bearing for cli-guard's discoverability. ## Recommendation Default to (1) unless the site has known external readers. If killing the site is on the table at all, (2) beats (3): the inline renderer adds maintenance surface that has to keep pace with goldmark + urfave/cli-docs. ## Action - Pick an option. - For (1): close this issue with a short comment noting "keep-frozen, will revisit if it breaks." - For (2) or (3): land the code change, close on commit. ## Prior art - agentic-os-kai#365 - archive of cli-web-docs (parent decision)
coilysiren added
P3
 and removed
P2
 labels 2026-05-31 07:00:14 +00:00
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
v0.1.0
Labels
Clear labels
  
P0
now / blocking / urgent

  
P1
next / important

  
P2
backlog / will do

  
P3
someday / low

  
P4
icebox / frozen / reopen if it becomes real

No labels
P0
P1
P2
P3
P4
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
coilyco-flight-deck/cli-guard#24
No description provided.