4.10 System Context Management

The Standard ecosystem relies on a clear and centralized context architecture. The objective is to eliminate any information drift between various development tools, autonomous AI agents, and humans working on the repository.

1. Architectural Decision Record (ADR)

Context & Problem Statement

The repository contains multiple entry points for configuration and instructions automatically loaded by IDEs or AI tools based on their editor (e.g., .github/copilot-instructions.md, CLAUDE.md, GEMINI.md, AGENTS.md). Without a clear structure, development rules and architectural explanations end up duplicated, modified in one file, and forgotten in others, creating major inconsistencies.

Decision

We establish a hub-and-spoke context structure based on the following principles:

1. Single Source at the Root: The root README.md file is the single entry point and absolute source of truth for the entire monorepo.
2. Strict Redirection: All other AI-specific instruction files contain no rules of their own. They systematically and exclusively redirect to the README.md or the Standards Manual.
3. Concepts live with their projects (July 2026 — the pillar files were
   dissolved): each project’s README.md opens with its why — the Vault in
   vault/README.md, the Standard in packages/README.md, the Garden in
   apps/stnd.gd/README.md. The project board (dashboard + aggregated tasks)
   lives inside the root README.md itself, so opening the repo folder in
   Obsidian (folder-note → README) shows map and state together.
4. Published norms are the bookshelf: the Standard::* books plus the
   framework reference, at stnd.build/manual — fed live from the repo
   (package and app READMEs are globbed directly, no copy step).

2. Context Flow Graph

The diagram below illustrates how information sources converge and distribute within the repository:

graph TD
  subgraph AI_Entry ["AI Entry / Editors"]
    G["GEMINI.md"]
    C["CLAUDE.md"]
    A["AGENTS.md"]
    COP[".github/copilot-instructions.md"]
  end

  subgraph Root ["Single Source (Root)"]
    R["README.md — map + project board"]
  end

  subgraph Projects ["Project READMEs (each opens with its why)"]
    STD["packages/README.md — the Standard"]
    VAU["vault/README.md — the Vault"]
    GAR["apps/stnd.gd/README.md — the Garden"]
  end

  subgraph Shelf ["The bookshelf (stnd.build/manual)"]
    BOOKS["Standard::* norm books"]
    FW["Standard::Framework — package READMEs, live"]
  end

  subgraph Narrative ["Philosophical Documentation (stnd.gd)"]
    GUI["GUIDE.md"]
    G_CONT["Guide Modules Content"]
  end

  G -->|Points to| R
  C -->|Points to| R
  A -->|Points to| R
  COP -->|Points to| R

  R -->|Substrate| VAU
  R -->|Rules| STD
  R -->|Publication| GAR

  STD -->|Conforms to| BOOKS
  STD -->|Globbed live| FW
  GAR -->|Feeds| GUI
  GUI --> G_CONT

3. Context Writing Rules

Any modification to an architectural rule or technical standard must:

1. First be documented in the affected file or folder (e.g., the README.md of a package, or a system page of the Manual).
2. Update the corresponding norm book on the bookshelf, or GUIDE.md for narrative changes.
3. Respect the Relative Path Rule (see 4.9 README Standards) to ensure that AI agents and editors resolve and navigate links without error.