WFGY/ProblemMap/Atlas/README.md

<!--
AI_NOTE_START

Document role:
This page is the main hub and navigation index for the Atlas folder.

How to use this page:
1. Treat this page as the central entry point for all Atlas system documents.
2. Use this page to understand document roles, reading order, and current freeze status.
3. Do not confuse this hub with the product-facing main page.
4. The product-facing main page is:
   ProblemMap/wfgy-ai-problem-map-troubleshooting-atlas.md

What this page is:
- A folder-level atlas hub
- A document map
- A stable navigation layer for humans and AI systems
- A bridge between product-facing and engineering-facing assets

What this page is not:
- Not the public homepage
- Not the full freeze document itself
- Not the full casebook
- Not the full adapter spec
- Not the full patch log
- Not the internal validation ledger

Reading discipline for AI:
- Preserve the distinction between atlas core, negative space, casebook, adapter, and fix layers.
- Respect frozen terms and patch discipline.
- Do not silently merge work-branches into frozen structures.
- Use linked documents according to their intended role.

Routing guidance:
- For product overview, go to the main product page first.
- For stable atlas structure, go to Atlas Final Freeze v1.
- For limits and safe expansion, go to Negative Space Report v1.
- For teaching and examples, go to Canonical Casebook v1.
- For AI-facing routing logic, go to Atlas-to-AI Adapter v1.
- For repair-facing materials, go to the Fixes folder.

AI_NOTE_END
-->

# Atlas Hub

## Problem Map 3.0 Troubleshooting Atlas
## Folder index, freeze map, and document routing layer

This folder is the structured vault for the Atlas system.

The main product-facing page lives here:

[Problem Map 3.0 Troubleshooting Atlas](../wfgy-ai-problem-map-troubleshooting-atlas.md)

This `README.md` is not the public homepage.
It is the **system hub** for the Atlas folder.

Its job is simple:

- show what documents exist
- show what role each document plays
- show what is already frozen
- show what is still patch-driven
- help humans and AI systems enter the atlas without getting lost

In short:

> the main product page introduces the atlas  
> this hub explains how the atlas folder is organized

---

## Current status

The current atlas system should be read as a multi-layer structure with a stable first formal release.

At the moment, the following major assets are already established:

- atlas core structure
- negative-space boundary logic
- integrated handoff logic
- canonical casebook layer
- AI adapter layer
- fix and repair-facing layer

This means the project is no longer in the stage of “trying to find the core.”

It is now in the stage of:

- structured extension
- patching
- teaching
- productization
- AI-facing reuse
- repair-surface thickening
- broader bridge building

---

## Recommended reading order

Different readers need different entry paths.

### Path A · first-time reader

1. [Problem Map 3.0 Troubleshooting Atlas](../wfgy-ai-problem-map-troubleshooting-atlas.md)
2. [Atlas Final Freeze v1](./atlas-final-freeze-v1.md)
3. [Canonical Casebook v1](./canonical-casebook-v1.md)
4. [Atlas-to-AI Adapter v1](./atlas-to-ai-adapter-v1.md)

Use this path if you want the shortest route from “what is this” to “how does this work.”

### Path B · engineering / system reader

1. [Atlas Final Freeze v1](./atlas-final-freeze-v1.md)
2. [Atlas Negative Space Report v1](./atlas-negative-space-report-v1.md)
3. [Atlas v1 Integrated Handoff](./atlas-v1-integrated-handoff.md)
4. [Atlas-to-AI Adapter v1](./atlas-to-ai-adapter-v1.md)

Use this path if you want the frozen core, its boundaries, and the current system routing logic.

### Path C · teaching / onboarding reader

1. [Canonical Casebook v1](./canonical-casebook-v1.md)
2. [Atlas Final Freeze v1](./atlas-final-freeze-v1.md)
3. [Fixes Hub](./Fixes/README.md)

Use this path if you want to teach, explain, or onboard new readers.

### Path D · repair / execution reader

1. [Fixes Hub](./Fixes/README.md)
2. [Atlas-to-AI Adapter v1](./atlas-to-ai-adapter-v1.md)
3. [Atlas Final Freeze v1](./atlas-final-freeze-v1.md)

Use this path if you want to connect routing to first repair direction and deeper repair-facing work.

---

## Folder map

This folder is organized around a few major document families.

### 1. Core atlas documents

These define the stable mother structure.

- [Atlas Final Freeze v1](./atlas-final-freeze-v1.md)  
  The positive structure document.  
  Defines the seven-family mother table, routing rules, canonical layer, subtree layer, relation matrix, fix-facing layer, and patch protocol.

- [Atlas Negative Space Report v1](./atlas-negative-space-report-v1.md)  
  The limit and boundary document.  
  Defines what remains intentionally open, weak, unpromoted, or patch-sensitive.

- [Atlas v1 Integrated Handoff](./atlas-v1-integrated-handoff.md)  
  The official delivery overview.  
  Explains how `Final Freeze v1` and `Negative Space v1` should be read together.

---

### 2. Teaching and case documents

These teach how to actually use the atlas.

- [Canonical Casebook v1](./canonical-casebook-v1.md)  
  The first formal teaching layer.  
  Includes family anchor cases, boundary teaching cases, and repair teaching cases.

---

### 3. AI-facing adapter documents

These compress atlas logic into a reusable routing layer for models and systems.

- [Atlas-to-AI Adapter v1](./atlas-to-ai-adapter-v1.md)  
  The main AI adapter asset.  
  Includes core contract, routing stack, casebook injection logic, runtime modes, patch interface, and adapter discipline.

---

### 4. Fix and repair-facing documents

These connect atlas diagnosis to first repair direction and deeper repair work.

- [Fixes Hub](./Fixes/README.md)  
  The main repair-facing entry point.  
  Connects official fixes, community fix lab, templates, demos, and advanced repair directions.

---

## What is already frozen

The following can now be treated as stable first-version assets:

### Frozen atlas body

- seven-family mother table
- major family boundary rules
- canonical node layer
- family-entry layer
- high-value subtree layer
- relation matrix v1
- patch protocol

### Frozen teaching body

- first canonical casebook structure
- family anchor cases
- boundary teaching cases
- repair teaching cases

### Frozen AI adapter body

- adapter contract
- routing stack
- runtime discipline
- model-facing routing logic

### Frozen repair-facing body

- first repair-facing entry layer
- family fix surface direction
- official fixes hub structure
- first flagship repair demos

---

## What is intentionally not fully frozen

The system is stable, but not fully closed.

The following areas remain intentionally open or patch-sensitive:

- work-branches not yet promoted
- weak or medium relations
- deeper subtree thickening
- broader cross-domain bridge evidence
- stronger repair-surface integration
- more compact and deployable TXT layers
- public packaging refinement
- deeper auto-repair planning layers

This is not a weakness.
It is part of the atlas design discipline.

The current project is meant to be:

> frozen at the core,  
> open at the edges,  
> and disciplined in growth.

---

## Cross-domain growth direction

This atlas is currently grounded in AI troubleshooting, routing, teaching, and repair-first workflows.

Its first formal release should be understood as:

- AI-first in its most validated public form
- already structured enough to support broader bridge work
- designed to grow through disciplined expansion rather than silent redefinition

Future work will continue extending the atlas toward broader complex-system and cross-domain debugging settings, including areas such as:

- coordination and consensus failures
- institutional drift and closure failures
- value, knowledge, and coherence failures
- broader civilization-scale debugging frames

This should be understood as a **bridge in development**, not as a claim of universal completion.

---

## What future work should not do

Future work should not:

- silently rewrite frozen structures
- promote branches by rhetoric alone
- flatten family, node, subtree, and overlay into one level
- confuse patching with core instability
- overstate bridge evidence as universal closure
- erase the distinction between public pages and internal system documents

These rules matter because the atlas is now a versioned system, not a floating concept.

---

## What future work should do

The highest-value next directions are:

### Repair-surface thickening
Strengthen the diagnosis-to-repair layer and keep the bridge into deeper repair logic clean.

### TXT deployment
Turn the adapter logic into a stronger text-native control pack.

### Demo expansion
Build cleaner human-facing and AI-facing demos.

### Cross-domain bridge expansion
Extend the atlas carefully beyond AI-first troubleshooting without overclaiming total completion.

### Product-facing distillation
Make the system easier to enter without flattening the structure.

---

## Official wording

When describing the current system in a new window, collaboration thread, or product workflow, use wording like this:

> Problem Map 3.0 Troubleshooting Atlas now has a frozen first body of core atlas documents, a canonical teaching layer, an AI-facing routing adapter, and a repair-facing fix layer.  
> Future work proceeds through patching, thickening, productization, and controlled bridge expansion.

This wording is strong, accurate, and safe.

---

## Practical usage guide

### For product work
Start with:
- [Problem Map 3.0 Troubleshooting Atlas](../wfgy-ai-problem-map-troubleshooting-atlas.md)

### For system and routing work
Start with:
- [Atlas Final Freeze v1](./atlas-final-freeze-v1.md)
- [Atlas-to-AI Adapter v1](./atlas-to-ai-adapter-v1.md)

### For teaching and onboarding
Start with:
- [Canonical Casebook v1](./canonical-casebook-v1.md)

### For repair and execution work
Start with:
- [Fixes Hub](./Fixes/README.md)

### For bridge and future expansion framing
Start with:
- this hub page first
- then the frozen core documents
- then the teaching and fix layers
- then future bridge documents as they are formally added

---

## One-line status

**The atlas core is frozen, the teaching layer exists, the AI adapter exists, and the repair-facing layer exists. Further work proceeds in patch mode and controlled bridge expansion.**

---

## Closing note

This folder is where the atlas becomes a real system.

The main page tells you what the product is.  
This hub tells you how the system is organized.  
The linked documents tell you how to use it, teach it, extend it, and connect it to repair-facing workflows and broader bridge work.

If the main product page is the front gate, this folder is the control room.