Skill: Doc-CLI Usage

Use the Rust-based documentation CLI for common tasks.

When to Use

• •Starting development environment
• •Building documentation
• •Deploying documentation
• •Bumping versions
• •Validating site configuration (agents)
• •Checking navigation coverage (agents)
• •Understanding project structure (agents)
• •Any routine documentation task

Critical: Background Server for AI Agents

When running as an AI agent, always start the server in the background so you can continue using the terminal for other commands:

# Start server in background (REQUIRED for agents)
cd /workspaces/my-life-as-a-dev && nohup ./doc-cli serve > /tmp/server.log 2>&1 &

# Wait for server to be ready
sleep 3

# Verify server is running
curl -s -o /dev/null -w "%{http_code}" http://localhost:8001/ || echo "Server not ready"

Why this matters:

• •AI agents need the terminal to run other commands (git, tests, agent-browser, etc.)
• •Foreground servers block the terminal until manually stopped
• •Using nohup with & allows the server to run independently
• •Logs go to /tmp/server.log for debugging if needed

To restart the server:

# Kill existing, then start fresh in background
./doc-cli kill && nohup ./doc-cli serve > /tmp/server.log 2>&1 &

To check server logs:

tail -f /tmp/server.log

Running Doc-CLI

# Recommended: wrapper script (builds if needed)
./doc-cli.sh

# Or direct binary (if already built)
./scripts/rust/target/release/doc-cli

Interactive Mode

Run without arguments for interactive menu:

./doc-cli.sh

Shows menu:

1. •serve - Start Zensical dev server (primary)
2. •build - Build with Zensical
3. •kill - Stop running servers
4. •bump-version - Create new version
5. •deploy - Publish to GitHub Pages
6. •info - Show project structure (useful for agents)
7. •validate - Validate configuration
8. •nav-check - Check navigation coverage h. help - Show commands

Commands

serve (Primary)

Start Zensical development server:

./doc-cli.sh serve

Features:

• •20x faster builds than MkDocs
• •Hot reload on file changes
• •Runs on port 8001

build

Build site with Zensical:

./doc-cli.sh build

Output goes to site/ directory.

kill

Stop running Zensical/MkDocs processes:

./doc-cli.sh kill

Kills processes by name and frees ports 8000/8001. Useful before restarting:

./doc-cli.sh kill && ./doc-cli.sh serve

mkdocs-serve (Legacy)

Start MkDocs development server:

# In Codespaces (auto-detected)
./doc-cli.sh mkdocs-serve

# Local development
./doc-cli.sh mkdocs-serve --local

# With full rebuilds (when hot reload misbehaves)
./doc-cli.sh mkdocs-serve --local --clean

Options:

• •--local - Required for local development (outside Codespaces)
• •--clean - Use full rebuilds instead of dirty mode (slower but reliable)

bump-version

Create new documentation version:

./doc-cli.sh bump-version

Prompts for:

• •Version type (major/minor/patch)
• •Confirmation

deploy

Deploy to GitHub Pages:

./doc-cli.sh deploy

# Force redeploy
./doc-cli.sh deploy --force

info (Agent Command)

Show project structure and configuration info:

./doc-cli.sh info

Displays:

• •Project paths (root, docs, overrides, stylesheets)
• •Configuration file status (zensical.toml, mkdocs.yml)
• •Key directory status
• •Markdown file count
• •Tips for agents

validate (Agent Command)

Validate site configuration:

./doc-cli.sh validate

Checks:

• •zensical.toml syntax and required fields
• •docs directory structure
• •Required files (index.md, overrides, stylesheets)

Returns exit code 1 on errors.

nav-check (Agent Command)

Check for markdown files not in navigation:

./doc-cli.sh nav-check

Reports:

• •Total markdown files found
• •Files referenced in navigation
• •Orphaned files not in nav

Useful for ensuring all pages are accessible.

help

Show available commands:

./doc-cli.sh help

Agent Workflow

When working on this repository, agents should:

1. •Run info first to understand project structure
2. •Run validate to check configuration
3. •Run nav-check after adding new pages
4. •Run build to verify changes compile

# Typical agent workflow
./doc-cli.sh info
./doc-cli.sh validate
# ... make changes ...
./doc-cli.sh nav-check
./doc-cli.sh build

Building Doc-CLI

The wrapper script builds automatically, but if needed:

cd scripts/rust
cargo build --release

Binary location: scripts/rust/target/release/doc-cli

Troubleshooting

Command Not Found

# Use wrapper script
./doc-cli.sh

# Or full path to binary
./scripts/rust/target/release/doc-cli

Build Errors

cd scripts/rust
cargo clean
cargo build --release

Port Already in Use

# Use kill command
./doc-cli.sh kill

# Then restart
./doc-cli.sh serve

WSL Issues

If doc-cli misbehaves on WSL, use make commands directly:

make setup
make serve

When to Use What

Configuration

This project uses modular configuration in config/zensical/:

These merge into zensical.toml automatically during serve and build.

Legacy Config

Always edit files in config/zensical/ - never edit zensical.toml directly.

Checklist

• • Wrapper script exists: ./doc-cli.sh
• • Running from project root
• • Virtual environment active (for Python operations)