Live study-docs showroom Markdown remains the source of truth Generated 2026-06-04

tracedocs (CLI sample)

Evidence-grounded project docs your team and AI agents can trust — every operational claim cites a source file, and gaps are stated instead of invented.

Explore the docs Open raw Markdown View index.json

Source: tracedocs @ cli branch · Generated by the tracedocs skill · This preview adds no facts beyond the committed Markdown docs and index.json.

Trust At A Glance

14
Verified claims
1
Inferred claim
0
Unknown claims
1
Needs confirmation

Hallucination Test

Generic AI docs often write

"Push to main; CI builds a Docker image and deploys to AWS ECS."

Looks plausible. Not supported by the sampled source.

tracedocs writes

No deployment configuration was found. The sampled source has no Dockerfile, no CI workflow, no Makefile, and no hosting-provider config.

Evidence: 03-deployment-manual.md + assumptions.md

Evidence Trace

Claim pytest -q runs the test suite.
→
Evidence pyproject.toml dev dependency + tests/.
→
Confidence Verified

Document Showroom

Project Overview
maintainers
Verified

tracedocs is a deterministic, offline CLI that scans a repository and writes a structured study-docs/ package.

  • Python 3.9+ with zero runtime dependencies.
  • Extracts commands, entry points, env-var names, routes, entities, tests, and deployment signals.
  • Writes manuals plus an evidence trail for agent handoff.
EvidenceConfidence
pyproject.toml, project_to_study/*.py, tests/Verified
Quickstart
anyone running it
Verified

Copy-paste commands are sourced from package metadata and tests.

python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
tracedocs /path/to/repo --out study-docs
pytest -q
EvidenceConfidence
pyproject.toml scripts/dev deps; tests/Verified
Operation Manual
operators
Verified

Documents day-to-day execution, validation, and local troubleshooting for a zero-service CLI: no daemon, no database, no runtime env vars.

EvidenceConfidence
cli.py, validate.py, model.pyVerified
Deployment Manual
deployers
Verified

No deployment configuration was found. This is the signature behaviour: tracedocs records the gap instead of inventing a cloud pipeline.

  • No Dockerfile.
  • No CI workflow.
  • No hosting-provider config.
EvidenceConfidence
Absence of Dockerfile, .github/workflows/, MakefileVerified
Learning Manual
learners / AI builders
Verified

Turns the repo into a reading path: start with CLI entry, follow source acquisition, scan facts, analyze routes/entities, then read the writer.

EvidenceConfidence
cli.py, source.py, scanner.py, writer.pyVerified
Code Introduction
developers / AI agents
Verified

Maps the core pipeline from cli.main through scanning, analysis, Markdown generation, evidence writing, and validation.

EvidenceConfidence
cli.py, scanner.py, analyzers.py, evidence.pyVerified
Architecture
technical maintainers
Inferred

Shows the deterministic extraction pipeline and calls out the main tradeoff: heuristic extraction is fast and simple, but can miss unusual code styles.

EvidenceConfidence
model.py, scanner.py, analyzers.pyVerified / Inferred risk
API & Integrations
developers
Verified

There is no HTTP API. The public surface is the CLI: generate, validate, and --version. The only external integration is optional git clone --depth 1.

EvidenceConfidence
cli.py, source.pyVerified
Data Model
developers
Verified

No database. The model is a set of in-memory dataclasses: ProjectFacts, Command, EnvVar, Route, Entity, and Claim.

EvidenceConfidence
model.py, writer.pyVerified
Troubleshooting
anyone debugging
Verified

Common failures are concrete: command not found, bad target path, missing git for Git URLs, broken links in generated docs, and secret leakage checks.

EvidenceConfidence
source.py, validate.py, tests/Verified
Maintenance
contributors / AI agents
Needs confirmation

Documents the safe change workflow and the confirmed gap: PyPI publishing and release cadence are not configured in this repository.

EvidenceConfidence
pyproject.toml, absent publish workflow, tests/Verified / Needs confirmation

AI-ready index.json

Agents do not need to parse prose first

The package ships a compact manifest of docs, commands, confidence counts, unknowns, evidence files, routes, and entities.

11documents
3verified commands
2unknowns recorded
3evidence files
{
  "commands": {
    "install": "pip install -e \".[dev]\"",
    "run": "tracedocs <path> --out study-docs",
    "test": "pytest -q"
  },
  "confidence": {
    "verified": 14,
    "inferred": 1,
    "needs_confirmation": 1
  }
}

How it was built

Any repo→ 1 Analyze→ 2 Evidence map→ 3 Write manuals→ 4 Quality check→ study-docs/*.md index.json _evidence/