Skip to content

docs: OSS-style README, brand banner, and user guide under docs/guide#67

Merged
davideimola merged 1 commit into
mainfrom
docs/readme-and-user-guide
Jul 13, 2026
Merged

docs: OSS-style README, brand banner, and user guide under docs/guide#67
davideimola merged 1 commit into
mainfrom
docs/readme-and-user-guide

Conversation

@davideimola

Copy link
Copy Markdown
Contributor

What

Reworks the repo's front door in the style of well-known OSS dev tools (fastify, gin, cobra, charm, kubernetes) and stands up a task-oriented user guide.

README

  • Centered brand banner (<picture>, light/dark variants) replaces the H1; tagline + badge row (CI, release, Go Reference, Go Report Card, license — the Go/pkg.go.dev badges light up once the repo is public).
  • Flow: what Argus is → why it exists → compact quickstart → features → channel table → built-in skills → docs links → pre-1.0 status.
  • Reference material (full config, command table, upgrade notes, project layout) moved out to the guide; no internal companion docs cited.
  • Fixes a factual error: Slack was presented as an existing channel — only github/mcp/tui exist today, so it is now marked planned.

Brand

  • brand/argus-banner-{light,dark}.svg: feather + wordmark + "application security agent" lockup, system fonts only (no external assets).

Docs restructure (by audience)

  • docs/guide/ (new, user-facing): getting started, argus.yaml reference, GitHub channel (auto reviews, bare-name vocative, security posture), MCP channel, skills guide, and deployment/kubernetes.md moved in with links fixed.
  • docs/design/: authz-skill-design*.md moved out of the docs root.
  • docs/skills/ removed: the authz-audit companion README duplicated the design doc and the new skills guide — and it can't live next to the skill in pkg/skill/builtin/ because //go:embed all:builtin would bundle it into the binary as a skill file. User-facing content now lives in docs/guide/skills.md.
  • CONTEXT.md, docs/adr/, docs/agents/ untouched (paths fixed by the grilling conventions).

Verification

  • Script-checked that every relative markdown link in the repo resolves.
  • Banner SVGs rendered and visually verified in both light and dark variants.

🤖 Generated with Claude Code

Rework the repo's front door for readers coming from the talk, modeled on
the READMEs of fastify, gin, cobra, charm, and kubernetes:

- README: centered brand banner + tagline + badge row, then what/why,
  a compact quickstart, features, the channel table, built-in skills,
  and a docs link list. Reference material moved out to the guide; no
  internal companion docs cited. Slack is now marked as planned (only
  github/mcp/tui channels exist today).
- brand: argus-banner-{light,dark}.svg lockups (feather + wordmark +
  "application security agent"), picked by <picture> per color scheme.
- docs/guide/: new task-oriented user guide — getting started,
  configuration reference, GitHub and MCP channel guides, skills guide,
  and the kubernetes page moved under deployment/.
- docs/design/: authz-skill-design*.md moved out of docs root.
- docs/skills/ removed: the authz-audit companion README duplicated the
  design doc and the new skills guide, and it cannot live next to the
  skill itself because go:embed all:builtin would bundle it into the
  binary as a skill file.

All relative markdown links verified to resolve.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@davideimola
davideimola merged commit 1e7b7cb into main Jul 13, 2026
3 checks passed
@davideimola
davideimola deleted the docs/readme-and-user-guide branch July 13, 2026 15:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant