AIV documentation map

This map separates authored product guidance from examples, benchmark evidence, generated output, and internal review records. Readers can follow the public path without navigating research artifacts.

Start here

  1. README: product overview and entry points.
  2. Quick start: build, choose a profile, run locally/strictly.
  3. Hello World: exercise all 16 gates one by one.
  4. Gate map: open one gate.
  5. Module adoption guide: mandatory/optional modules and profiles.
  6. Architecture: eight PNG figures with detailed explanations.

Public product guides

Document Purpose
TUTORIAL.md first successful run
HELLO-WORLD.md complete hands-on lab
GATES.md one gate at a time
MODULE-ADOPTION-GUIDE.md gate/module/profile decisions
DEVELOPER-CONFIGURATION.md all config keys/defaults
DEPLOYMENT.md local/CI deployment
PRE-COMMIT.md commit-time workflow
MCP.md strict verify contract
AIDLC.md AI-DLC plugin/sensors
EVIDENCE-AND-PROPOSALS.md audit/report/proposal commands
CI-SNIPPETS.md non-GitHub CI examples
PLUGIN-SECURITY.md security gate operations
WHY-NOT-PMD-SEMGREP.md complementary tool positioning

Developer and architecture references

Document Purpose
ARCHITECTURE.md full system/module/runtime/trust/integration design
DEVELOPER-GUIDE.md build, tests, new gates
MAVEN-VERSION.md version and artifact coordinates
../aiv-api/README.md model/port contract
../aiv-*/README.md detailed guide for each of 24 child modules

Narrative and diagrams

Artifact Purpose
Technical article long-form technical narrative
images/ architecture and gate diagrams used by the docs

Evidence and review records

Location Classification
benchmarks/airflow-bench-compare/ regression/experimental evidence with methodology limits
benchmarks/proposal-pilot/ proposal-check pilot outputs
docs/reports/ query examples and generated evidence support
docs/apache/ historical ecosystem analysis, not primary product positioning

Generated Markdown

Files under benchmark results/ directories are generated evidence. They should be regenerated by their owning script rather than manually rewritten for tone. Public product claims must not be inferred from generated fixture summaries without reading the methodology.

Examples and integrations

Location Purpose
example-project/ consumer configuration/workflow example
demos/public-seed/ small pass/fail demonstration fixtures
integrations/aidlc/ standalone adapter and complete AI-DLC plugin source
presets/ explicit starter policies
scripts/ install/version/doc validation helpers

Documentation validation

python scripts/validate-docs.py
python docs/images/validate_visuals.py

The doc validator checks all local Markdown links, all 24 module READMEs, prohibited punctuation, stale image references, and minimum module-guide sections.

Author: Viquar Khan