Complete local operating contract positioning across docs and guidance

.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
@@ -104,7 +109,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/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/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/technical-overview.md

@@ -2,11 +2,20 @@
 
 ## 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 +27,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 +94,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

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