# Documentation Inventory And Consolidation Record

Status: active consolidation record. Last audited: 2026-07-16.

## Objective

`public/docs/` is the single canonical documentation tree for StratoFusion.
Root and source-folder Markdown may remain when it has a distinct repository,
tooling, compatibility, prompt, or historical-evidence purpose, but it must
point to canonical public documentation and must not redefine current runtime
truth.

No source documentation was deleted in this consolidation. Deletion remains a
separate approval-gated step.

## Inventory

The audit used `rg --files -g '*.md'` and excluded generated or dependency
trees: `.git`, `.next`, `node_modules`, `dist`, `build`, `coverage`,
`storybook-static`, `playwright-report`, `test-results`, and
`test-results-archive`.

| Area                   | Markdown files | Approximate lines | Classification                                                                     |
| ---------------------- | -------------: | ----------------: | ---------------------------------------------------------------------------------- |
| `public/docs/`         |            253 |            60,714 | Canonical topics, derived ChatGPT sources, and explicitly historical collections.  |
| `docs/`                |             21 |             4,359 | Live AI skills plus VM rehearsal, cutover, runbook, and cost worklogs.             |
| Other repository paths |             28 |             6,571 | Root overviews/plans, compatibility pointers, prompts, and source-module pointers. |
| **Total**              |        **302** |        **71,644** | Maintained Markdown after adding the architecture status and VM runbook documents. |

`src/app/docs/` contains no Markdown sources in this checkout. Documentation
route implementation lives in `src/app/dev/docs/`, `src/components/docs/`, and
`src/lib/docs.ts`; it reads Markdown from `public/docs/`.

## Canonical Status Model

Architecture claims use the definitions in
[Architecture Evolution](./ARCHITECTURE_EVOLUTION.md):

- **Current**: OVHcloud VM Compose production stack.
- **Legacy**: former Vercel production, Neon production, and Fly.io rclone
  production/development resources retained for history or approved recovery.
- **Transitional**: Phase-B hostnames and OAuth opt-in, Phase-C write freeze,
  Neon restore tooling, and legacy reconciliation paths.
- **Planned**: future provider/AI Search capabilities, automatic Fly scaling,
  multi-host VM architecture, automated database failover, shared-development
  migration, and destructive legacy-resource retirement.

Dated bugfixes, prompts, checklists, investigations, and consolidation records
preserve the state at the time they were written. They are evidence, not current
runtime authority.

## Major Overlap Areas

### Runtime Architecture And Operations

Sources overlapped across `README.md`, `agents.md`, `docs/runbook.md`, the VM
worklogs, `DEPLOYMENT.md`, `RCLONE_SERVICE.md`, and the ChatGPT upload bundle.
Current runtime classification is now maintained in:

- [Architecture](./ARCHITECTURE.md)
- [Architecture Evolution](./ARCHITECTURE_EVOLUTION.md)
- [Deployment](./DEPLOYMENT.md)
- [Rclone Service](./RCLONE_SERVICE.md)
- [Production VM Runbook](./operations/VM_PRODUCTION_RUNBOOK.md)

### AI Search Planning

Nine root `AI_Search_Plan*.md` files overlap and sometimes describe alternative
future infrastructure. Implemented and planned behavior is consolidated in:

- [AI Search Architecture](./developer/modules/AI_SEARCH_ARCHITECTURE.md)
- [AI Search Infrastructure Ports](./developer/modules/AI_SEARCH_INFRA_PORTS.md)
- [AI Search Indexing Adapters](./developer/modules/AI_SEARCH_INDEXING_ADAPTERS.md)
- [AI Search Grounded Answers](./developer/modules/AI_SEARCH_RAG.md)

The root plans remain cleanup candidates because they preserve design history
but are not runtime truth.

### Source-Module Documentation

README files under `src/`, `scripts/`, and `fly-rclone/` are compatibility
pointers. Their canonical targets are developer module guides,
`DEVELOPMENT_SCRIPTS.md`, `RCLONE_SERVICE.md`, `SWAGGER_UI_SETUP.md`, and the
operations guide for rclone utilities.

### ChatGPT Project Sources

`public/docs/chatgpt-project-sources/` is a derived, flat upload bundle. It is
not a second canonical tree. Its manifest maps every source to canonical docs,
and compact source summaries should be refreshed only after canonical docs.

### Historical Feature And Fix Reports

`archive/`, `bugfixes/`, `consolidation-history/`, dated fix reports, diagrams,
and migration reports intentionally preserve implementation-time detail. They
remain under `public/docs/` but are classified as historical. Current subsystem
behavior belongs in topic docs and the architecture/deployment documents.

## Source Mapping Outside `public/docs/`

### Root Files

| Source                          | Canonical replacement                                   | Disposition                               |
| ------------------------------- | ------------------------------------------------------- | ----------------------------------------- |
| `README.md`                     | `PROJECT_OVERVIEW.md`, `ARCHITECTURE_EVOLUTION.md`      | Keep as GitHub-facing overview.           |
| `agents.md`                     | `developer/AI_OPERATING_PROTOCOL.md`, architecture docs | Keep because tooling consumes it.         |
| `docs-inventory.md`             | this document                                           | Compatibility pointer; cleanup candidate. |
| `ENVIRONNENTS.md`               | `DEPLOYMENT.md`, OAuth operations guide                 | Compatibility pointer; cleanup candidate. |
| root `AI_Search_Plan*.md` files | AI Search developer module guides                       | Historical planning; cleanup candidates.  |

### `docs/`

| Source                                      | Canonical replacement or interpretation       | Disposition                                                        |
| ------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------ |
| `docs/ai-skills/*.md`                       | canonical topic docs referenced by each skill | Keep as live, focused agent-operating summaries.                   |
| `docs/runbook.md`                           | `operations/VM_PRODUCTION_RUNBOOK.md`         | Superseded pre-consolidation runbook; cleanup candidate.           |
| `docs/phase-b-checklist.md`                 | `DEPLOYMENT.md`, `ARCHITECTURE_EVOLUTION.md`  | Keep as completed migration evidence.                              |
| `docs/local-vm-rehearsal.md`                | historical deployment section                 | Keep as local rehearsal evidence; not current production guidance. |
| `docs/cutover-phase-c-worklog.md`           | architecture status, deployment, VM runbook   | Keep as detailed cutover evidence.                                 |
| `docs/dependency-cost-reduction-worklog.md` | architecture/deployment summaries             | Keep as internal cost and resource-decision evidence.              |

### Other Source Pointers

| Source group                      | Canonical location                               |
| --------------------------------- | ------------------------------------------------ |
| `fly-rclone/README.md`            | `RCLONE_SERVICE.md`                              |
| `fly-rclone/SWAGGER_UI_SETUP.md`  | `SWAGGER_UI_SETUP.md`                            |
| `fly-rclone/src/utils/README.md`  | `operations/FLY_RCLONE_UTILITIES.md`             |
| `scripts/README.md`               | `DEVELOPMENT_SCRIPTS.md`                         |
| `src/config/services/README.md`   | `developer/modules/SERVICE_CONFIGURATION.md`     |
| `src/config/transfer-filters.md`  | `developer/modules/TRANSFER_FILTERS.md`          |
| `src/hooks/README.md`             | `developer/modules/HOOKS_REFERENCE.md`           |
| `src/lib/rclone/README.md`        | `developer/modules/RCLONE_MODULE.md`             |
| `src/services/README.md`          | `developer/modules/SERVICE_ABSTRACTION_LAYER.md` |
| `src/services/adapters/README.md` | `developer/modules/SERVICE_ADAPTER_PATTERN.md`   |
| `src/tests/README.md`             | `developer/modules/TESTING_STRATEGY.md`          |
| `src/types/README.md`             | `developer/modules/TYPE_DEFINITIONS.md`          |
| root `prompts/*.md` pointers      | `public/docs/prompts/`                           |

## Contradictions Resolved

| Contradiction                                                                         | Resolution and evidence                                                                                                                                                               |
| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Fly.io described as the current data plane while VM docs describe a completed cutover | Production uses the VM rclone container. The VM workflow, Compose file, Caddy routes, and manual-only stopped Fly configuration support this. `Fly` names remain compatibility names. |
| Vercel described as current production app and scheduler                              | Vercel production is legacy. `.github/workflows/deploy.yml` deploys the VM from `main`; Compose owns the current app and one cron replica.                                            |
| Neon described as authoritative production state                                      | Compose PostgreSQL is current production. Neon production is a legacy restore/reconciliation source. Development may still use Neon.                                                  |
| Phase B and Phase C described as future work                                          | The cutover worklog records completion and a post-cutover production write. Rehearsal and freeze mechanisms are transitional/historical.                                              |
| Hetzner and OVHcloud both named as the public VM provider                             | Current executable and completed-cutover evidence identifies OVHcloud. Hetzner references remain in unexecuted rehearsal/provisioning records and are historical.                     |
| Old Vercel Cron diagrams conflict with current scheduler                              | Current production uses one Compose cron replica. Old diagrams and setup sections are historical implementation records.                                                              |
| Plans imply automatic Fly or multi-VM scaling                                         | No active implementation was found. These remain planned only.                                                                                                                        |

## Documentation UI And Navigation

- `/dev/docs` reads from `public/docs/` through the filesystem-backed catch-all
  route.
- Any canonical Markdown file is addressable by its relative path without a
  hard-coded route entry.
- Curated aliases and sidebar entries expose both
  `/dev/docs/architecture-evolution` and
  `/dev/docs/vm-production-runbook`.
- `INDEX.md`, developer, and operations hubs link the current VM architecture,
  previous Fly.io model, and production runbook.
- Relative Markdown links are converted to docs routes by `src/lib/docs.ts`.

## Documents That Remain For A Distinct Purpose

- `README.md`: repository landing page.
- `agents.md`: live agent/tooling protocol.
- `docs/ai-skills/`: task-focused operating summaries required by repo workflow.
- VM phase/worklog documents: detailed historical evidence and audit trail.
- `public/docs/archive/`, `bugfixes/`, `consolidation-history/`, `migrations/`,
  and dated reports: historical or forensic context.
- `public/docs/prompts/`: reusable, time-bound instructions; prompt state does
  not imply implementation state.
- `public/docs/chatgpt-project-sources/`: derived upload bundle with a manifest.
- source-folder README pointers: lightweight code-directory navigation until
  cleanup is explicitly approved.

## Deletion Proposal — Approval Required

No deletion was performed. The following are redundant enough to consider in a
separate cleanup:

1. `docs/runbook.md` after confirming the new VM runbook contains every still
   needed command.
2. `docs-inventory.md` and `ENVIRONNENTS.md`, now compatibility pointers.
3. The nine root AI Search planning files after confirming their unique design
   history is no longer needed outside the canonical AI Search guides.
4. Source-folder and root prompt compatibility pointers after confirming no
   tooling or developer workflow relies on their paths.

Do not delete the VM cutover worklog, Phase-B checklist, local rehearsal,
dependency/cost worklog, agent skills, root README, agent protocol, or canonical
historical collections solely because newer architecture exists.

## Verification Targets

- Inventory counts can be reproduced with `scripts/audit-all-docs.sh` under
  Git Bash or an equivalent PowerShell/`rg` audit.
- Canonical relative links resolve to existing files or approved assets.
- Docs catalog entries refer to existing Markdown files and have unique slugs.
- Focused route and docs utility tests pass.
- `/dev/docs/index`, `/dev/docs/architecture-evolution`, and
  `/dev/docs/vm-production-runbook` render through the local documentation UI.
- The ChatGPT upload manifest contains every file in the derived bundle and no
  stale file entry.
- Searches for current-runtime claims are reconciled against architecture
  status; remaining Fly/Vercel/Neon references are compatibility, environment,
  legacy, planned, or historical statements.