chore: add CLAUDE.md and .claude project config

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2 files changed, 202 insertions, 0 deletions

diff --git a/.claude/settings.local.json b/.claude/settings.local.json
new file mode 100644
index 00000000..08146991
--- /dev/null
+++ b/.claude/settings.local.json
@@ -0,0 +1,111 @@
+{
+  "env": {
+    "RTD_TOKEN": "3950c3c5298ef12d7e78134a922f09811f7da37a"
+  },
+  "permissions": {
+    "allow": [
+      "Bash(find /Users/syncer/GitHub/vyos-documentation -name *.sh -type f)",
+      "WebFetch(domain:docs.readthedocs.com)",
+      "Skill(update-config)",
+      "Bash(curl -s -H \"Authorization: Token $RTD_TOKEN\" \"https://app.readthedocs.com/api/v3/projects/\")",
+      "Bash(python3 -m json.tool)",
+      "Bash(curl -s -H 'Authorization: Token $RTD_TOKEN' https://app.readthedocs.org/api/v3/projects/)",
+      "Bash(curl -s -H \"Authorization: Token 3950c3c5298ef12d7e78134a922f09811f7da37a\" \"https://app.readthedocs.org/api/v3/projects/?limit=50\")",
+      "Bash(curl -s -H \"Authorization: Token 3950c3c5298ef12d7e78134a922f09811f7da37a\" \"https://app.readthedocs.org/api/v3/projects/vyos/versions/?limit=100\")",
+      "Bash(curl -s -H \"Authorization: Token 3950c3c5298ef12d7e78134a922f09811f7da37a\" \"https://app.readthedocs.org/api/v3/projects/vyos/builds/?limit=20\")",
+      "Bash(curl -s -H \"Authorization: Token 3950c3c5298ef12d7e78134a922f09811f7da37a\" \"https://app.readthedocs.org/api/v3/projects/vyos/redirects/?limit=100\")",
+      "Bash(curl -s -H \"Authorization: Token 3950c3c5298ef12d7e78134a922f09811f7da37a\" \"https://app.readthedocs.org/api/v3/projects/vyos/environmentvariables/\")",
+      "Bash(curl -s -H \"Authorization: Token 3950c3c5298ef12d7e78134a922f09811f7da37a\" \"https://app.readthedocs.org/api/v3/projects/vyos/translations/\")",
+      "Bash(curl -s -H \"Authorization: Token 3950c3c5298ef12d7e78134a922f09811f7da37a\" \"https://app.readthedocs.org/api/v3/projects/vyos/subprojects/\")",
+      "Bash(curl -s -H \"Authorization: Token 3950c3c5298ef12d7e78134a922f09811f7da37a\" \"https://app.readthedocs.org/api/v3/projects/vyos/?expand=active_versions\")",
+      "Bash(xargs awk:*)",
+      "Bash(grep -v \": $\")",
+      "Bash(grep -v \": 0$\")",
+      "Bash(sort -t: -k2 -rn)",
+      "Bash(while read:*)",
+      "Bash(do if:*)",
+      "Bash(then echo:*)",
+      "Bash(find . -name \"*.rst\" -exec wc -l {})",
+      "Bash(find . -name *.rst)",
+      "Bash(fi)",
+      "Bash(done)",
+      "Bash(grep -rn '^TBD$\\\\|^   TBD$\\\\|^TODO\\\\|^.. TODO\\\\|FIXME\\\\|XXX' --include=\"*.rst\" .)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(grep -rP t /Users/syncer/GitHub/vyos-documentation/docs/ --include=*.rst -l)",
+      "Bash(for f:*)",
+      "Bash(do echo:*)",
+      "Read(//Users/syncer/GitHub/vyos-documentation/docs/**)",
+      "Bash(grep -rP t /Users/syncer/GitHub/vyos-documentation/docs/ --include=*.rst -c)",
+      "Bash(grep -v ':0$')",
+      "Bash(git checkout:*)",
+      "Bash(for slug:*)",
+      "Bash(python3 -m json.tool echo \"\" done)",
+      "Bash(do)",
+      "Bash(echo \"=== $slug ===\")",
+      "Bash(curl -s -o /dev/null -w \"HTTP %{http_code}\\\\n\" -X PATCH -H \"Authorization: Token 3950c3c5298ef12d7e78134a922f09811f7da37a\" -H \"Content-Type: application/json\" -d '{\"\"hidden\"\": true}' \"https://app.readthedocs.org/api/v3/projects/vyos/versions/$slug/\")",
+      "Bash(curl -s -H \"Authorization: Token 3950c3c5298ef12d7e78134a922f09811f7da37a\" \"https://app.readthedocs.org/api/v3/projects/vyos/redirects/\")",
+      "Bash(python3 -c \":*)",
+      "Bash(python3:*)",
+      "Bash(git push:*)",
+      "Bash(gh pr:*)",
+      "Bash(gh api:*)",
+      "Bash(gh run:*)",
+      "Bash(xargs -I{} gh api repos/vyos/vyos-documentation/actions/jobs/{}/logs)",
+      "Bash(grep -v '^\\\\s*$')",
+      "Bash(find /Users/syncer/GitHub/vyos-documentation -type f -name .vale* -o -name vale.ini -o -name vale.toml -o -name .vale.ini)",
+      "Bash(cat /Users/syncer/GitHub/vyos-documentation/.github/workflows/*.yml)",
+      "Bash(grep -r \"vyoslinter\\\\|linter\" /Users/syncer/GitHub/vyos-documentation --include=*.py --include=*.md --include=*.sh)",
+      "Bash(grep -r \"RFC\\\\|non-RFC\\\\|IP address\\\\|line too long\" /Users/syncer/GitHub/vyos-documentation --include=*.py --include=*.md --include=*.toml --include=*.ini)",
+      "Bash(xargs cat:*)",
+      "Bash(find /Users/syncer/GitHub/vyos-documentation -name *linter* -o -name vale*)",
+      "Bash(find /Users/syncer/GitHub/vyos-documentation/docs/_include/vyos-1x -name *linter* -o -name *vale*)",
+      "Bash(git config:*)",
+      "Bash(git cherry-pick:*)",
+      "Bash(awk 'length > 80' docs/automation/terraform/terraformvSphere.rst)",
+      "Bash(awk 'length > 80' docs/configuration/interfaces/openvpn-examples.rst)",
+      "Bash(awk:*)",
+      "Bash(for pr:*)",
+      "Bash(/dev/null done:*)",
+      "Bash(curl -s -H \"Authorization: Token 3950c3c5298ef12d7e78134a922f09811f7da37a\" \"https://app.readthedocs.org/api/v3/projects/vyos/versions/?slug=1803\")",
+      "Bash(curl -s -H \"Authorization: Token 3950c3c5298ef12d7e78134a922f09811f7da37a\" \"https://app.readthedocs.org/api/v3/projects/vyos/builds/?limit=5\")",
+      "WebFetch(domain:docs.vyos.io)",
+      "WebFetch(domain:sphinx-sitemap.readthedocs.io)",
+      "Bash(brew list:*)",
+      "Bash(pip3 list:*)",
+      "Bash(pip3 install:*)",
+      "Bash(brew install:*)",
+      "Bash(pandoc --version)",
+      "Bash(pandoc:*)",
+      "Bash(vale --version)",
+      "Bash(grep -rn vyoslinter /Users/syncer/GitHub/vyos-documentation/ --include=*.yml --include=*.yaml --include=*.sh --include=*.cfg --include=*.ini)",
+      "Bash(git restore:*)",
+      "Bash(echo \"=== PR #$pr ===\")",
+      "Bash(grep -v \"^vyos-1x$\")",
+      "Bash(/Users/syncer/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.5/scripts/start-server.sh --project-dir /Users/syncer/GitHub/vyos-documentation)",
+      "Bash(/Users/syncer/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.5/skills/brainstorming/scripts/start-server.sh --project-dir /Users/syncer/GitHub/vyos-documentation)",
+      "Bash(git -C /Users/syncer/GitHub/vyos-documentation ls-files --error-unmatch .superpowers)",
+      "Bash(git:*)",
+      "Bash(gh auth:*)",
+      "Read(//Users/syncer/GitHub/phorge-mcp/**)",
+      "Read(//Users/syncer/GitHub/release-notes/**)",
+      "Bash(find ~/GitHub/phorge-mcp -name .env* -o -name *.key -o -name *.pem -o -name secrets*)",
+      "Bash(find /Users/syncer/GitHub/vyos-documentation -name llms.txt -o -name .well-known -o -name *ai-*)",
+      "Bash(pip3 search:*)",
+      "Bash(pip3 index:*)",
+      "WebSearch",
+      "WebFetch(domain:pypi.org)",
+      "WebFetch(domain:rst-to-myst.readthedocs.io)",
+      "WebFetch(domain:myst-parser.readthedocs.io)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:gist.github.com)",
+      "WebFetch(domain:documenteer.lsst.io)",
+      "WebFetch(domain:projectpythia.org)",
+      "WebFetch(domain:developers.cloudflare.com)",
+      "WebFetch(domain:docs.github.com)",
+      "WebFetch(domain:about.readthedocs.com)",
+      "WebFetch(domain:www.netlify.com)",
+      "WebFetch(domain:www.readsthedocs.com)"
+    ]
+  }
+}
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..3496d223
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,91 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+VyOS network OS documentation, built with Sphinx from reStructuredText sources. Hosted at https://docs.vyos.io. The `current` branch tracks VyOS 1.5.x (circinus) rolling release.
+
+## Build Commands
+
+All build commands run from the `docs/` directory.
+
+### Local (requires Sphinx installed via `pip install -r requirements.txt`)
+
+```bash
+cd docs
+make html              # Build HTML to docs/_build/html/
+make livehtml          # Live preview at http://localhost:8000
+make pdf               # Generate PDF
+```
+
+### Docker (preferred)
+
+```bash
+# Build HTML
+docker run --rm -it -v "$(pwd)":/vyos -w /vyos/docs -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) vyos/vyos-documentation make html
+
+# Live preview
+docker run --rm -it -p 8000:8000 -v "$(pwd)":/vyos -w /vyos/docs -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) vyos/vyos-documentation make livehtml
+```
+
+### Linting (Vale)
+
+```bash
+# Lint all files
+docker run --rm -it -v "$(pwd)":/vyos -w /vyos/docs -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) vyos/vyos-documentation vale .
+
+# Lint a single file
+docker run --rm -it -v "$(pwd)":/vyos -w /vyos/docs -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) vyos/vyos-documentation vale quick-start.rst
+```
+
+## Architecture
+
+### Documentation Source
+
+- All RST source files live under `docs/` following the VyOS CLI hierarchy (e.g., `set firewall zone` → `docs/configuration/firewall/zone.rst`)
+- Main index: `docs/index.rst`
+- Sphinx config: `docs/conf.py`
+
+### Custom Sphinx Extensions (`docs/_ext/`)
+
+- **vyos.py** — Core extension defining custom directives and roles:
+  - `.. cfgcmd::` — Document configuration commands
+  - `.. opcmd::` — Document operational commands
+  - `.. cfgcmdlist::` / `.. opcmdlist::` — Generate command lists with coverage status
+  - `.. cmdinclude::` — Include RST with variable substitution (var0-var9)
+  - Roles: `:vytask:` (links to task tracker), `:cfgcmd:`, `:opcmd:` (inline command references)
+- **testcoverage.py** — Compares documented commands against XML definitions and actual VyOS commands
+- **releasenotes.py** — Release notes integration
+
+### Shared Fragments (`docs/_include/`)
+
+- `interface-*.txt` files contain shared RST blocks (e.g., common interface options) included via `.. cmdinclude::` with `var0`–`var9` substitution
+- `vyos-1x/` submodule contains VyOS source XML definitions used for command coverage analysis
+
+### Additional Extensions
+
+- **autosectionlabel.py** — Custom wrapper enabling cross-document section references via `autosectionlabel_prefix_document = True`
+- Both `.rst` and `.md` (MyST Markdown) are valid source formats
+
+## RST Writing Conventions
+
+- **Language**: American English
+- **Line length**: Max 80 characters (URLs exempt)
+- **Indentation**: 2 spaces
+- **Heading hierarchy** (top to bottom): `#####`, `*****`, `=====`, `-----`, `^^^^^`, `""""""`
+- Every RST file must start with the `#####` level title
+- Leave a newline before and after headers
+- Quote commands/filenames with double backticks; use literal blocks for longer snippets
+- Add `:lastproofread: YYYY-MM-DD` metadata to track proofreading currency (warns if >365 days old)
+
+### Page Structure
+
+Each documentation page should follow this order:
+1. Theoretical information (what/why/when)
+2. Configuration description (using `cfgcmd` directives)
+3. Configuration examples with topology
+4. Known issues and workarounds
+5. Debugging procedures
+
+### Update `index.rst` when adding new pages.