docs: ADR-087 documentation overhaul (Phases 1-3)

[aaronsb]

Summary

Implements ADR-087 documentation strategy with audience-organized documentation.

The Real Point

This isn't just a knowledge graph. It's infrastructure for AI agents that can reason about what they know and how well they know it.

What's New

Phase 1: Concepts (non-technical foundation)

• docs/concepts/README.md - 30-second explanation
• docs/concepts/how-it-works.md - Conceptual model without code
• docs/concepts/glossary.md - Plain-language definitions

Phase 2: Operating (operator guides)

• docs/operating/README.md - Overview and quick commands
• docs/operating/quick-start.md - 5-minute local setup
• docs/operating/production.md - Full deployment with headless init, HTTPS, GPU
• docs/operating/configuration.md - All settings reference
• docs/operating/upgrading.md - Version upgrade procedures
• docs/operating/backup-restore.md - Data protection
• docs/operating/troubleshooting.md - Common issues and fixes

Phase 3: Using (user guides)

• docs/using/README.md - Entry point for users
• docs/using/ingesting.md - Adding documents
• docs/using/exploring.md - Finding and navigating concepts
• docs/using/querying.md - CLI, API, and MCP access
• docs/using/understanding-grounding.md - Confidence and contradiction

Six Audiences (from ADR-087)

Audience	Served By
Builder pair (us)	ADRs, .claude/ tracking
Operators	docs/operating/
Users	docs/using/
Developers	docs/architecture/, docs/reference/
AI agents	MCP docs, epistemic model explanation
Non-technical	docs/concepts/

Stats

• 15 new/updated files
• ~2,650 lines of documentation
• Phases 4 (reference) already existed (auto-generated)
• Phase 5 (agent integration) deferred as future/research

Test Plan

• Verify cross-references between docs work
• Check concepts/README captures "The Real Point"
• Confirm operating/production.md matches actual headless-init parameters
• Review for consistency with ADR-087 specification

[aaronsb]

Documentation Review: ADR-087 Implementation

Reviewed the documentation overhaul against ADR-087 requirements and actual implementation. Overall this is a strong implementation of the documentation strategy - well-organized, audience-appropriate, and largely accurate.

Summary

Category	Status
Consistency	Minor issues
Completeness vs ADR-087	Phases 1-3 complete, reference links pending
Accuracy	One parameter discrepancy
Audience appropriateness	Excellent
Quality	A few broken links, minor gaps

---

1. Consistency

Terminology is consistent across documents. Key terms (concept, grounding, ontology, source, evidence) are used uniformly. The glossary definitions match usage in other docs.

Cross-references are mostly accurate but there are issues:

• docs/using/querying.md:174 - Links to ../reference/api/README.md
• docs/using/querying.md:279 - Links to ../reference/mcp/README.md

These reference directories exist but contain only stubs. The OpenAPI spec exists at docs/reference/openapi.json but there's no rendered README. Consider either:

1. Generating the READMEs from existing auto-generated docs
2. Linking directly to the OpenAPI spec
3. Removing these links until Phase 4 is complete

---

2. Completeness vs ADR-087

Phase 1 (Concepts): Complete

• README.md with 30-second explanation
• how-it-works.md with conceptual model
• glossary.md with plain-language definitions

Phase 2 (Operating): Complete

• All 7 planned documents present
• Covers quick-start through troubleshooting

Phase 3 (Using): Complete

• All 5 planned documents present
• Task-oriented structure as specified

Missing from ADR-087 spec but noted as deferred:

• Phase 4 (Reference) - partially exists (auto-generated), needs polish
• Phase 5 (Agent Integration) - explicitly deferred

The PR accurately represents scope - Phases 1-3 are complete per the specification.

---

3. Accuracy Verification

production.md vs headless-init.sh

Verified accurate:

• --headless, --container-prefix, --image-source, --gpu options match
• --web-hostname, --ai-provider, --ai-model, --ai-key all correct
• --password-mode, --container-mode, --skip-ai-config, --skip-cli all match

Minor discrepancy at docs/operating/production.md:49:

The table shows --compose-file default as docker-compose.yml, which is correct, but the actual behavior (lines 362-366 of headless-init.sh) automatically switches to docker-compose.prod.yml when using --container-prefix=kg or --image-source=ghcr. This is mentioned in configuration.md:130-137 but not in production.md.

Suggest adding a note that compose file auto-selects based on prefix/source.

configuration.md vs .env.example

Coverage is good but some variables documented in .env.example are missing from configuration.md:

• Token cost configuration (TOKEN_COST_GPT4O, etc.) - lines 115-125 of .env.example
• Mock provider configuration (MOCK_MODE) - lines 72-74
• Rate limiting per-provider fallbacks (OPENAI_MAX_CONCURRENT, etc.) - lines 183-191
• Embedding model configuration (EMBEDDING_MODEL, EMBEDDING_DIMENSIONS) - lines 279-280

These are advanced/optional, so may be intentional omissions. Consider adding a brief "Advanced Configuration" section or noting where to find complete reference.

CLI Commands in querying.md

Issue at docs/using/querying.md:49-58:

The documented commands:

kg concept details <concept-id>
kg concept related <concept-id>
kg concept connect --from "concept A" --to "concept B"

Actual CLI structure (from search.ts):

kg search details <concept-id>
kg search related <concept-id>
kg search connect <from> <to>

The commands are subcommands of search, not a top-level concept command. Similarly:

• docs/using/README.md:49-52 - same issue
• docs/using/exploring.md:56-57, 79, 99-103, 114-115 - same issue

This affects multiple files and should be corrected.

Similarly, at docs/using/querying.md:30-31:

kg auth login
kg auth logout

These are actually registered as:

kg login
kg logout

The auth prefix doesn't exist in the CLI - these are top-level commands.

---

4. Audience Appropriateness

concepts/ - Non-technical: Excellent

• No code in conceptual explanations
• Plain language throughout
• The "30-second version" genuinely takes 30 seconds
• Glossary uses analogies and examples effectively

operating/ - Operator-focused: Good

• Appropriately focused on deployment and configuration
• Not developer-focused (no code internals)
• Commands are actionable and copy-paste ready
• One concern: quick-start.md assumes git is installed but doesn't mention it in prerequisites (line 8)

using/ - Task-oriented: Good

• Organized by what users want to accomplish
• Examples are practical
• Progressive from simple to advanced

---

5. Quality Issues

Broken/Pending Links

• docs/using/querying.md:174 -> ../reference/api/README.md (empty)
• docs/using/querying.md:279 -> ../reference/mcp/README.md (empty)

Minor Gaps

docs/operating/quick-start.md:8 - Prerequisites should mention Git

docs/using/exploring.md:148-149:

kg search "vaccination effects" --show-contested

This --show-contested flag doesn't appear to exist in the CLI. The actual approach would be to search and look for low grounding scores.

docs/using/exploring.md:165:

kg vocabulary list --status CONTESTED

Should be kg vocab list (short form) and the --status flag appears to be --filter or similar based on the vocabulary command structure.

docs/using/understanding-grounding.md:126-128:

kg vocabulary list --status CONTESTED
kg search "topic" --status AFFIRMATIVE

Same issues - commands need verification against actual CLI implementation.

Formatting Consistency

• Tables in production.md use consistent formatting
• Code blocks are properly fenced
• No inconsistent heading levels detected

---

Recommendations

Must fix before merge:

1. Update CLI command examples to use actual command structure (kg search details not kg concept details, kg login not kg auth login)

Should fix:
2. Add note about compose file auto-selection in production.md
3. Fix or remove broken reference links
4. Add Git to quick-start prerequisites
5. Verify vocabulary/search flag names match implementation

Consider for future:
6. Add "Advanced Configuration" section to configuration.md
7. Complete Phase 4 reference documentation

---

AI-assisted review via Claude. Verified against headless-init.sh, .env.example, and cli/src/cli/.ts.*