Standardize Core Document maintenance headers and index output formats

.github/copilot-instructions.md

@@ -5,10 +5,11 @@ exist to point Copilot at the same repository-owned rules used by other coding
 agents; they do not replace `AGENTS.md`, `CONTRIBUTING.md`, `STANDARDS.md`, or
 the `.ai-context/` orientation files.
 
-Keep Base focused as the shared developer workspace control plane. Project
-application code, project-specific setup, service behavior, and one-off local
-machine preferences belong in the owning project unless Base is explicitly the
-right shared layer.
+Keep Base focused as the local operating contract for deterministic readiness
+and handoff across independent Git repositories. Its durable loop is inventory
+-> prepare -> verify -> trust -> onboard -> hand off. Project application code,
+project-specific setup, service behavior, and one-off local machine preferences
+belong in the owning project unless Base is explicitly the right shared layer.
 
 For implementation work, use Base's issue-backed workflow:
 

AGENTS.md

@@ -7,7 +7,9 @@ them.
 ## Working Agreement
 
 - Follow `CONTRIBUTING.md` for workflow and `STANDARDS.md` for code standards.
-- Keep Base focused as the shared developer workspace control plane.
+- Keep Base focused as the local operating contract for deterministic readiness
+  and handoff across independent Git repositories. Its durable loop is
+  inventory -> prepare -> verify -> trust -> onboard -> hand off.
 - Keep project-specific setup, service code, and application behavior in the
   owning project repository unless Base is explicitly the right shared layer.
 - Adopt external agent workflow ideas only after translating them into

CONTRIBUTING.md

@@ -1,7 +1,9 @@
 # Contributing to Base
 
 Base is a developer tooling repository. Contributions should keep the project
-opinionated, testable, and useful as a shared workspace control plane.
+opinionated, testable, and useful as a local operating contract for deterministic
+readiness and handoff across independent Git repositories. The durable product
+loop is inventory -> prepare -> verify -> trust -> onboard -> hand off.
 
 ## AI-Assisted Development
 

FAQ.md

@@ -1,5 +1,18 @@
 # Base FAQ
 
+## What Is Base?
+
+Base is a local operating contract for deterministic readiness and handoff
+across independent Git repositories. Its durable loop is:
+
+```text
+inventory -> prepare -> verify -> trust -> onboard -> hand off
+```
+
+Base makes a participating repo set understandable and locally ready while
+projects keep ownership of their application behavior, services, and
+project-specific setup.
+
 ## First-Time Installation
 
 ### What should I run on a blank macOS machine?
@@ -148,8 +161,8 @@ while `base_cli` answers "how should a Base Python CLI behave?" See the
 
 Base's reusable Bash helpers live in the standalone
 `basefoundry/base-bash-libs` repository so other scripts can reuse the logging,
-command execution, filesystem, and Git conventions without depending on the
-full Base workspace control plane.
+command execution, filesystem, and Git conventions without depending on Base's
+full local operating contract for multi-repository readiness and handoff.
 
 That separation also keeps the Homebrew packaging path cleaner: `base-bash-libs`
 can mature as its own formula, and a future Homebrew/core Base formula can

docs/README.md

@@ -17,6 +17,11 @@ see [Release Process](release-process.md).
 For self-guided or live walkthrough material, see
 [Presentations](presentations/README.md).
 
+Base's product outcome is a local operating contract for deterministic readiness
+and handoff across independent Git repositories. The durable loop is
+inventory -> prepare -> verify -> trust -> onboard -> hand off. See [Why Base](why-base.md)
+for the concise product framing; the map below links to the deeper references.
+
 ## Internal Planning Artifacts
 
 The `docs/superpowers/` directory contains agent-written planning artifacts
@@ -50,6 +55,8 @@ reference. The filename should answer "what is this about?"
   skill evidence.
 - [Command Quick Reference](command-reference.md) is the one-page lookup table
   for the current `basectl` command surface and important flags.
+- [Output Formats](output-formats.md) defines the shared text and machine-readable
+  report format contract used by `basectl` inspection commands.
 - [Stability Tiers](stability-tiers.md) defines which command, JSON, finding ID,
   generated artifact, and helper surfaces are stable, experimental, or internal.
 - [Inspection JSON](inspection-json.md) defines the shared stable envelope and
@@ -104,7 +111,8 @@ reference. The filename should answer "what is this about?"
 - [Base Presentations](presentations/README.md) documents the presentation
   source-of-truth and export policy.
 - [Base Newcomer Orientation](presentations/base-newcomer-orientation.md)
-  introduces Base as a workspace control plane for multi-repo development.
+  introduces Base as a local operating contract for deterministic readiness and
+  handoff across independent repositories.
 
 ## Feature And Boundary Documents
 

docs/architecture.md

@@ -1,5 +1,8 @@
 # Base Architecture
 
+Status: maintained architecture reference
+Last reviewed: 2026-07-25
+
 ## Overview
 
 Base is an opinionated macOS-primary implementation of a local operating

docs/base-bash-libs.md

@@ -4,7 +4,8 @@ Base's reusable Bash libraries live in the standalone
 [`basefoundry/base-bash-libs`](https://github.com/basefoundry/base-bash-libs)
 repository. That repository lets scripts use Base's Bash logging, argument
 parsing, command execution, filesystem, Git, GitHub CLI, list, and string helper
-conventions without adopting the full Base workspace control plane.
+conventions without adopting Base's full local operating contract for
+multi-repository readiness and handoff.
 
 This page documents the Base-side consumption and post-migration contract. Library
 APIs and standalone examples live in the `base-bash-libs` repository.

docs/command-reference.md

@@ -1,5 +1,8 @@
 # basectl Quick Reference
 
+Status: maintained command reference
+Last reviewed: 2026-07-25
+
 This page is a compact lookup table for the current `basectl` command surface.
 Run `basectl help <nested path>` or append `--help` to that path for the same
 leaf-specific usage. Run `basectl --help` for the journey-oriented command map.

docs/execution-model.md

@@ -1,5 +1,8 @@
 # Base Execution Model
 
+Status: maintained runtime reference
+Last reviewed: 2026-07-25
+
 This document describes the current `basectl` execution contract. It is about
 what happens after a user invokes Base, not the future project-discovery or
 Python orchestration layers.

docs/presentations/README.md

@@ -8,7 +8,8 @@ of duplicating the reference text.
 ## Decks
 
 - [Base Newcomer Orientation](base-newcomer-orientation.md) introduces Base as
-  a workspace control plane for multi-repo development.
+  a local operating contract for deterministic readiness and handoff across
+  independent repositories.
 
 ## Source Of Truth
 

docs/presentations/base-newcomer-orientation.md

@@ -5,7 +5,8 @@ paginate: true
 
 # Base Newcomer Orientation
 
-Workspace control plane for multi-repo development
+Local operating contract for deterministic readiness and handoff
+across independent repositories
 
 Canonical product details live in the README and focused docs. This deck is an
 orientation path for GitHub readers and live walkthroughs.
@@ -24,17 +25,25 @@ A developer may need:
 - diagnostics that explain what is missing
 - shell activation without copying private dotfile logic into every repo
 
-Base gives that workspace a common operating layer.
+Base gives that workspace a common, inspectable operating contract.
 
 ---
 
 ## What Base Is
 
-Base is a workspace control plane.
+Base is a local operating contract for deterministic readiness and handoff
+across independent Git repositories.
 
-It discovers participating repositories, reads their Base contracts, and gives
-the developer one command surface for setup, diagnostics, tests, demos,
-activation, release support, and CI.
+It makes the repo set understandable, locally ready, explicitly trusted,
+onboardable, and transferable. Its durable loop is:
+
+```text
+inventory -> prepare -> verify -> trust -> onboard -> hand off
+```
+
+The `basectl` command surface supports setup, diagnostics, tests, demos,
+activation, release support, and CI while project repositories retain ownership
+of their application behavior.
 
 It does not turn sibling repositories into a monorepo.
 

docs/runtime-environment.md

@@ -1,5 +1,8 @@
 # Base Runtime Environment
 
+Status: maintained runtime contract
+Last reviewed: 2026-07-25
+
 This page is the canonical reference for Base-managed shell environment
 variables. It covers variables that are part of the runtime contract, command
 dispatch, project activation, and user-facing configuration knobs.

docs/stability-tiers.md

@@ -1,5 +1,8 @@
 # Base Stability Tiers
 
+Status: maintained compatibility reference
+Last reviewed: 2026-07-25
+
 Base exposes several surfaces that users and automation can depend on: CLI
 commands, JSON payloads, finding IDs, manifest schemas, generated files, and
 internal helper APIs. This page defines the stability vocabulary for those

docs/technical-overview.md

@@ -1,12 +1,24 @@
 # Base — Technical and Product Overview
 
+Status: maintained product and technical reference
+Last reviewed: 2026-07-25
+
 ## What It Is
 
-**Base** is a macOS-first workspace control plane for developers who keep multiple
-Git repositories checked out side by side under a shared directory (typically
-`~/work/`). Rather than forcing unrelated codebases into a monorepo, Base provides
-a single CLI — `basectl` — that orchestrates setup, diagnostics, project discovery,
-shell activation, test execution, and releases across all of them.
+**Base** is a macOS-first local operating contract for developers who work across
+multiple independent Git repositories checked out side by side under a shared
+directory (typically `~/work/`). Rather than forcing unrelated codebases into a
+monorepo, Base makes the repo set understandable, locally ready, explicitly
+trusted, onboardable, and transferable through one inspectable CLI contract.
+
+Its durable product loop is:
+
+```text
+inventory -> prepare -> verify -> trust -> onboard -> hand off
+```
+
+The `basectl` CLI provides the execution surface for that loop, including setup,
+diagnostics, project discovery, shell activation, test execution, and releases.
 
 > The repo you check out once per workspace so all other repos become easier to
 > set up, test, and run.
@@ -18,13 +30,14 @@ bootstrap story, and the glue between projects — shared env vars, shared tools
 consistent shell environments — lives in fragile ad-hoc dotfiles or one-off
 scripts. Base formalizes that glue without absorbing project-specific logic.
 
-It solves exactly three things:
+It gives the repo set a common, inspectable operating contract:
 
-1. **Umbrella setup and test** — one command to set up or test any project
-2. **Shell environment management** — one managed, inspectable shell layer across
-   the whole workspace
-3. **Shared Bash/Python libraries** — consistent CLI execution patterns for all
-   project scripts
+1. **Inventory** — identify participating repositories and their declarations.
+2. **Prepare** — reconcile the tools and environments those declarations need.
+3. **Verify and trust** — report readiness and require explicit consent before
+   running project-owned commands.
+4. **Onboard and hand off** — guide first use and preserve local evidence for the
+   next implementer without taking project behavior away from its owner.
 
 ## Target Workspace Shape
 
@@ -84,7 +97,7 @@ Spawns a Bash runtime shell, sets `BASE_PROJECT`, applies the project runtime
 route, runs `activate.source` scripts declared in the manifest, and updates the
 prompt to `[project: branch] ~/path $`. Python projects activate their selected
 project venv. Shell-only setup/check/doctor work does not create one solely for
-Base's control plane. Exit that shell to return to the original environment -
+Base's runtime. Exit that shell to return to the original environment -
 no deactivation logic needed.
 
 **Design choice — no `cd`-triggered activation:** switching directories does not

docs/tool-boundaries.md

@@ -1,11 +1,14 @@
 # Base Ecosystem Boundaries
 
+Status: maintained ecosystem boundary reference
+Last reviewed: 2026-07-25
+
 This document captures how Base should relate to other popular developer tools.
 Its purpose is not to compete with everything in the ecosystem. Its purpose is
 to help Base stay sharp about what it owns, what it can orchestrate, and what
 it should leave alone.
 
-Evidence checked: 2026-07-14
+Evidence checked: 2026-07-25
 
 When we evaluate another tool, we record five separate decisions:
 

docs/why-base.md

@@ -1,5 +1,8 @@
 # Why Base
 
+Status: maintained product entry point
+Last reviewed: 2026-07-25
+
 Base is a local operating contract for developers and platform engineers whose
 work spans multiple independent Git repositories. It makes a participating repo
 set understandable and locally ready without forcing a monorepo or taking

skills.md

@@ -98,8 +98,9 @@ public workflow docs.
 - For docs-only or configuration-only changes, `git diff --check` is usually
   enough unless the change affects CI validation or generated output.
 - Evaluate review feedback against Base's product boundaries before
-  implementing it. Base is the workspace control plane; project-specific
-  application behavior belongs in the owning project.
+  implementing it. Base is the local operating contract for deterministic
+  readiness and handoff; project-specific application behavior belongs in the
+  owning project.
 - If feedback suggests a larger design or product shift, stop and surface the
   decision instead of hiding it inside a small PR.
 

tests/test_github_workflows.py

@@ -642,7 +642,7 @@ def test_copilot_repository_instructions_stay_anchored_to_base_guidance() -> Non
     assert "STANDARDS.md" in text
     assert ".ai-context/" in text
     assert "issue-backed" in text
-    assert "Base focused as the shared developer workspace control plane" in text
+    assert "Keep Base focused as the local operating contract for deterministic readiness" in text
     assert "Do not require GitHub Copilot" in text