Skip to content

README.md

Latest commit

 

History

History
98 lines (84 loc) · 8.09 KB

README.md

File metadata and controls

98 lines (84 loc) · 8.09 KB
Raw

Transformation Portal Documentation

This directory contains both maintained operator documentation and historical records. Use this page for current navigation; point-in-time reports remain in place for audit context but are not live runbooks unless they are linked below as canonical documents.

Current baseline: repo-wide refresh audit dated May 11, 2026, building on main through PR #1721, with the May 12 architecture triage overlay for docs/architecture file dispositions and the May 12 CLI reference alignment for docs/cli.

Start Here

Need Current Document
Repository overview and setup Main README
Full documentation map Documentation Map
Documentation refresh audit 2026-05-11 Documentation Refresh Audit
Architecture triage inventory 2026-05-12 Architecture Inventory
CLI triage inventory 2026-05-12 CLI Inventory
Prior documentation state audit 2026-04-27 Documentation State Audit
Local setup and environment checks Setup Guide
Portal and orchestrator contracts Portal + Orchestrator Quickstart
Managed front door Portal Secure Front Door Quickstart
Managed paid-pilot staging Managed Paid-Pilot Staging Runbook
Lux Depth V3 CLI Lux Depth V3 CLI Guide
CLI entrypoint reference CLI Reference
FastVLM advisory captioning runtime FastVLM Runtime
CI workflow inventory Workflow Matrix

Current Maintained Surfaces

Area Canonical Docs Notes
Portal / API Portal Quickstart, API docs /healthz, /ready, /v1/readiness, and job lifecycle routes are current governed surfaces. PR #1562 and later follow-ups added typed OpenAPI response models while preserving existing wire contracts.
Secure front door Front Door Quickstart Node 22.x is the enforced local/runtime contract for web/secure-landing.
Managed paid-pilot staging Managed Paid-Pilot Staging Runbook, Paid-Pilot Managed-Services Smoke Gate Phase 5.A is locally validated at 07a3e8e847dee4a6e1ccf46d6dcd80b612fe3753; managed-provider validation remains pending until the same gate passes against provider Postgres, Redis, and S3-compatible storage.
Docker / environment Main README, .env.example Docker Compose reads the root .env template with required: false; set TP_API_KEY for non-throwaway runs.
CI / validation Workflow Matrix, CI/CD Workflows The current GitHub Actions inventory contains 30 workflows after the Phase 1.4 refresh.
Agent / Copilot guidance Custom Agent Guide, Agent Quick Reference, Copilot Instructions, CLAUDE.md Live agent behavior is governed by .github/agents/, Copilot instructions, CLAUDE.md, and docs/architecture/agent_governance.md.
Skill progression Skill Progress Tracks Maps recurring PR review themes to evidence-linked drills, acceptance tests, and review checklists.
TODO governance TODO Inventory, TODO Action Plan, TODO Quick Reference, TODO Priority Schema Current scanner-governed baseline: 24 governed NotImplementedError items, 0 ungoverned TODOs, snapshot refreshed May 11, 2026.
Archive gates Archive Machine Contract, 2026-04-27 Archive Gates Audit Gates A/B/C are documented with the April 27 readiness audit and normalized JSON evidence.
APEX / Materials APEX Governance Status, APEX Workflow Design, APEX Model Family Characterization Recent merges added offline model-family characterization, failure-code surfacing, confidence-only pixel-op passthrough, V2 fallback, and SAM2 tile-merge regression coverage.
CLI references CLI Index, CLI Reference, Lux Depth V3 CLI Guide, PBR CLI Testing Guide Maintained CLI docs use repo-governed .venv and Make targets; old PBR coverage/checklist and CLI v1.3 notes are historical evidence.
Advisory captioning FastVLM Runtime Optional subprocess-isolated sidecars only; captions are advisory and never satisfy APEX or Materials V3 gates.
Portal UX/UI planning Portal UX/UI Status Snapshot Current planning context through #1721; status snapshot only, not a next-PR selector.
Dependency policy ADR-032, Retired ML Lock Lanes, AGENTS.md Layered lockfiles and the Apple Silicon target-owned ML lane are the current dependency governance model.

Historical And Archive Material

The repo intentionally retains older project reports, PR notes, quality studies, and session artifacts. Treat these directories as historical unless a current map explicitly links a document as canonical:

  • docs/750_picacho/, docs/projects/, and docs/quality_analysis/ contain 2025 project-specific analysis and delivery records.
  • docs/depth_model/, docs/pipeline/, and docs/pipeline_docs/ contain older depth-model and luxury-pipeline evaluation material. Current depth behavior is described in the main README, CLI guide, and ADR-019/ADR-015.
  • docs/reports/, docs/status/, docs/session_summaries/, docs/sessions/, docs/historical/, and docs/pr_archive/ are point-in-time records.
  • docs/historical/architecture/ and docs/pr_archive/architecture/ contain files moved out of docs/architecture by the May 12 architecture triage.
  • docs/historical/cli/ contains point-in-time CLI implementation and coverage records moved out of current docs/cli navigation by the May 12 CLI alignment.
  • docs/_archive/ contains intentionally retired or consolidated material.

Do not use historical documents as operator runbooks without first checking the current documentation map.

Documentation Governance

make check-docs
make check-stale-docs
make check-doc-heading-links
python3 scripts/governance/check_docs_structure.py --all

Last Updated: 2026-05-15