Overview
Before docs-site/, DefenseClaw documentation lived in docs/*.md — a flat set of Markdown files inside the repo. Those files are retained for history but are not canonical for v7. Every topic has moved to a dedicated docs-site/ page with code-accurate generated content.
Mapping table
| Legacy file | Replacement |
|---|---|
docs/README.md | docs-site/index.mdx |
docs/INSTALL.md | Install methods |
docs/QUICKSTART.md | Zero to governed |
docs/CLI.md | CLI overview and the commands section |
docs/GUARDRAIL.md | Guardrail overview |
docs/POLICY.md | Policy engines |
docs/SCANNERS.md | Scanner catalog |
docs/WATCHER.md | Watcher overview |
docs/FIREWALL.md | Firewall overview |
docs/SANDBOX.md | Sandbox overview |
docs/OBSERVABILITY.md | Observability overview |
docs/API.md | API overview |
docs/DEVELOPMENT.md | Developer overview |
docs/RELEASE.md | Release |
docs/CONTRIBUTING.md | Contributing |
docs/FAQ.md | FAQ |
docs/GLOSSARY.md | Glossary |
docs/TROUBLESHOOTING.md | Troubleshooting |
docs/ARCHITECTURE.md | Architecture |
Why move?
- MDX over Markdown — we need callouts, diagrams, and code-reference blocks that Markdown alone doesn't do well.
- Autogeneration — CLI, schemas, env vars, and telemetry names are now generated directly from code into AUTOGEN blocks. The legacy Markdown would drift within weeks.
- Consistency with cisco-ai-defense.github.io — we publish docs to the shared site; our format matches the site's conventions.
- Navigation —
_meta/toc.jsondrives the sidebar for everyone. One source of truth.
What happens to the legacy files?
For v7.0: they still exist, they link to their replacements at the top, and a banner warns they're historical.
For v7.1 and beyond: the docs/ directory will be emptied except for a README.md that points at docs-site/. CI will fail PRs that add new files to docs/.
If you had bookmarks
The legacy paths don't redirect automatically (we can't control where your bookmark lives). Use the table above to find the replacement. If you can't find something, it's either:
- In docs-site/reference — we consolidated the small pages.
- Deprecated — the v7 architecture removed it.
File an issue if a topic you need isn't here. We'd rather add it than leave you stranded.