From ff2dca4e9ea25aacd94ca5a94af22c5da9121dea Mon Sep 17 00:00:00 2001 From: Ramesh Padmanabhaiah <22363102+codeforester@users.noreply.github.com> Date: Mon, 17 Aug 2026 06:45:30 +0530 Subject: [PATCH] docs: clarify terminology and boundaries --- FAQ.md | 2 +- README.md | 10 ++-- docs/README.md | 2 +- docs/architecture.md | 30 ++++------- docs/basectl-onboard.md | 21 ++------ docs/cache-ownership-and-layout.md | 2 +- docs/doctor-findings.md | 2 +- .../base-newcomer-orientation.md | 2 +- docs/product-assessment.md | 54 +++++++++---------- docs/product-requirements.md | 19 ++----- docs/technical-overview.md | 15 +++--- docs/tool-boundaries.md | 24 +++++---- docs/why-base.md | 6 +-- docs/workspace-manifest.md | 2 +- 14 files changed, 78 insertions(+), 113 deletions(-) diff --git a/FAQ.md b/FAQ.md index ffb53df8..9f6c2476 100644 --- a/FAQ.md +++ b/FAQ.md @@ -9,7 +9,7 @@ across independent Git repositories. Its durable loop is: inventory -> prepare -> verify -> trust -> onboard -> hand off ``` -Base makes a participating repo set understandable and locally ready while +Base makes a participating repository set understandable and locally ready while projects keep ownership of their application behavior, services, and project-specific setup. diff --git a/README.md b/README.md index ba8df663..1894557b 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ engineers. It gives a repeatable way to prepare, verify, test, build, and hand off a project, whether that project lives in one repository or spans multiple independent Git repositories. -It makes that project or repo set easier to inventory, prepare, verify, trust, +It makes that project or repository set easier to inventory, prepare, verify, trust, onboard, and hand off without turning it into a monorepo or moving project-specific logic into Base. @@ -54,7 +54,7 @@ Every engineering project accumulates setup steps, readiness rules, trusted commands, and handoff context that can become scattered across READMEs, shell state, and maintainer memory. That problem exists within a single repository and becomes more visible when work spans several repositories. Base gives a -project or participating repo set one explicit local contract for answering: +project or participating repository set one explicit local contract for answering: what belongs here, what is ready, what is missing, what may run, and what the next person or agent needs to know. @@ -777,7 +777,7 @@ run `basectl workspace configure` to apply the repair path. With non-Base-managed repositories, and continues after per-repo failures. Without a manifest, Base scans discovered local Base-managed projects under the workspace root. This is the fastest way to roll out shared repo or Project schema repairs -across a local repo family while keeping each repository's `repo configure` +across a local repository set while keeping each repository's `repo configure` behavior idempotent. Use `basectl workspace setup --dry-run` to preview project setup across the @@ -1897,7 +1897,7 @@ project is one repository or a set of independent Git repositories. A single repository can use Base to make setup, readiness, trusted execution, and handoff explicit. When a project spans several repositories, Base extends -the same contract across the repo set. Each project repo remains independent; +the same contract across the repository set. Each project repo remains independent; Base sits beside those repos and offers: - one declared way to inventory, prepare, and verify local readiness @@ -1969,7 +1969,7 @@ tracked in GitHub Issues using the workflow in ## Short Version -Base is the local operating contract you add to a repo set so its readiness, +Base is the local operating contract you add to a repository set so its readiness, trusted execution, onboarding, and handoff stop depending on private maintainer memory. diff --git a/docs/README.md b/docs/README.md index 84ce8e9c..c90f60b2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -147,7 +147,7 @@ reference. The filename should answer "what is this about?" model for executing project-owned manifest commands from unfamiliar repositories. - [Workspace Manifest](workspace-manifest.md) defines the local team-shared - repo-set contract and `basectl workspace --manifest` reporting behavior. + repository set contract and `basectl workspace --manifest` reporting behavior. - [Setup Hooks Boundary](setup-hooks.md) records why Base does not support arbitrary manifest setup hooks yet. - [`basectl setup` parallelism](setup-parallelism.md) records why setup stays diff --git a/docs/architecture.md b/docs/architecture.md index b503c430..eefdc012 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -44,7 +44,7 @@ machine-readable structures, and clear next actions from declared inputs and observable local state. It does not mean hermetic builds, byte-for-byte environments, or transactional multi-repository mutation. -The product responsibility layers are: +The product responsibility tiers are: 1. The core outcome: deterministic local readiness and handoff. 2. The enabling execution contract: `base_manifest.yaml`, `basectl`, @@ -53,7 +53,7 @@ The product responsibility layers are: conventions. 4. Adapters: environment managers, IDEs, containers, Nix/devenv, and AI tools. -These are architecture responsibility layers, not separately installed +These are architecture responsibility tiers, not separately installed packages. Major features should strengthen the outcome loop. A command does not become core merely because `basectl` dispatches it. @@ -196,8 +196,10 @@ basectl activate myproject ## Shell Environment Layers Base separates ordinary shell startup from Base runtime activation. +These shell environment layers are distinct from the product responsibility +tiers above; their numbering is local to shell startup and runtime state. -### Layer 1 — Dotfile Integration +### Shell Layer 1 — Dotfile Integration Applied by the user's normal Bash/Zsh startup files after running `basectl update-profile`. @@ -214,7 +216,7 @@ This layer must not source `base_init.sh` and must not establish the full Base runtime contract. It is only about Bash/Zsh startup behavior plus launcher availability. -### Layer 2 — Base Runtime Environment +### Shell Layer 2 — Base Runtime Environment Applied when the user invokes `basectl`, `basectl activate `, or `basectl /path/to/script.sh`. Invoking `basectl` with no arguments in a terminal @@ -237,7 +239,7 @@ live in [Runtime Environment](runtime-environment.md). The standalone `base-bash-libs` install path and post-migration contract live in [Base Bash Libraries](base-bash-libs.md). -### Layer 3 — Project-Specific Environment +### Shell Layer 3 — Project-Specific Environment Applied inside the project subshell when `basectl activate ` is run. @@ -598,7 +600,7 @@ parent manifest rather than auto-discovering everything. ### Workspace manifest -A workspace manifest is a team-shared repo-set contract. It is distinct from +A workspace manifest is a team-shared repository set contract. It is distinct from each project's `base_manifest.yaml`: the workspace manifest says which repositories should belong together, while project manifests say how each repository participates in Base. @@ -657,7 +659,7 @@ state, virtual environment state, and Git state across discovered projects, including invalid manifests without stopping the whole scan. With `workspace.manifest` or `--manifest `, workspace commands also report missing required repositories, missing optional repositories, and discovered -Base-managed projects outside the expected repo set. `basectl workspace check` +Base-managed projects outside the expected repository set. `basectl workspace check` and `basectl workspace doctor` run project checks and diagnostics across discovered projects. `basectl workspace onboarding` is a shipped read-only text or JSON summary of ready, needs-setup, invalid-manifest, missing-required, and @@ -818,18 +820,8 @@ These extras emerge organically from real needs — they are not designed upfron ## What Base Is Not -- Not a replacement for Docker or dev containers — those solve a different problem - (containerization). Base is local and lightweight. -- Not broadly cross-platform today — macOS remains the primary platform, while - Ubuntu/Debian source-checkout runtime and apt-backed setup are implemented. - Broader Linux distributions, WSL, and Windows are not supported today. -- Not a universal package manager — Homebrew handles that. Base orchestrates on top - of Homebrew. -- Not a generic multi-repository sync or command fan-out manager. -- Not a hosted agent runtime, live session-transfer service, or provider upload - system. -- Not trying to solve every edge case — version conflict handling across projects, - language runtimes beyond Python, and container integration are future considerations. +For the canonical non-goals and ecosystem boundary, see +[Tool Boundaries](tool-boundaries.md#what-base-is-not). --- diff --git a/docs/basectl-onboard.md b/docs/basectl-onboard.md index e5acb28a..571ca9e6 100644 --- a/docs/basectl-onboard.md +++ b/docs/basectl-onboard.md @@ -38,7 +38,7 @@ Options: ```text --profile Include named prerequisite profiles. --dry-run Explain and show planned actions without making changes. - --yes Accept setup/profile prompts; never approve manifest trust. + --yes Accept setup/profile prompts; never grant manifest trust. --no-profile Skip shell profile updates. -v Enable DEBUG logging for underlying commands. -h, --help Show help text. @@ -111,23 +111,8 @@ Those responsibilities already belong to the setup/check/profile commands. ## Command Shape -Command shape: - -```bash -basectl onboard [project] [options] -``` - -Options: - -```text - --profile Include named prerequisite profiles. - --dry-run Explain and show planned actions without making changes. - --yes Approve setup changes and the shell-profile prompt; never - grant manifest trust. - --no-profile Skip shell profile updates. - -v Enable DEBUG logging for underlying commands. - -h, --help Show help text. -``` +The command shape and canonical option descriptions are documented in +[Usage](#usage) above. The command defaults to the `base` project. Passing a project name targets the Base-managed project checks and setup steps without making Base responsible for diff --git a/docs/cache-ownership-and-layout.md b/docs/cache-ownership-and-layout.md index 0b78bd86..2f060992 100644 --- a/docs/cache-ownership-and-layout.md +++ b/docs/cache-ownership-and-layout.md @@ -58,7 +58,7 @@ $BASE_CACHE_DIR/ │ │ ├── base_setup/ │ │ └── base_github_projects/ │ └── runs/ - │ └── ____/ +│ └── ____/ │ ├── run.json │ ├── logs/ │ │ └── primary.log diff --git a/docs/doctor-findings.md b/docs/doctor-findings.md index 86cc0245..b04fc94a 100644 --- a/docs/doctor-findings.md +++ b/docs/doctor-findings.md @@ -127,7 +127,7 @@ Doctor commands use the same diagnostic item fields. The top-level | `BASE-D102` | Unsupported prerequisite profile version | | `BASE-D103` | Homebrew unavailable for prerequisite profile checks | | `BASE-D104` | Prerequisite profile Homebrew package presence and freshness | -| `BASE-D105` | GitHub CLI availability | +| `BASE-D105` | GitHub CLI executable availability for authentication checks | | `BASE-D106` | GitHub CLI authentication status | | `BASE-D107` | AI developer tool availability and version status | | `BASE-D108` | Multipass availability and version status for the `linux-lab` profile | diff --git a/docs/presentations/base-newcomer-orientation.md b/docs/presentations/base-newcomer-orientation.md index 16d9402b..3f60d26b 100644 --- a/docs/presentations/base-newcomer-orientation.md +++ b/docs/presentations/base-newcomer-orientation.md @@ -34,7 +34,7 @@ Base gives that workspace a common, inspectable operating contract. Base is a local operating contract for deterministic readiness and handoff across independent Git repositories. -It makes the repo set understandable, locally ready, explicitly trusted, +It makes the repository set understandable, locally ready, explicitly trusted, onboardable, and transferable. Its durable loop is: ```text diff --git a/docs/product-assessment.md b/docs/product-assessment.md index de11b9e3..f52abeca 100644 --- a/docs/product-assessment.md +++ b/docs/product-assessment.md @@ -56,9 +56,13 @@ across every repository and external tool. The execution contract (`base_manifest.yaml`, `basectl`, `base-wrapper`, and declared project commands) enables that outcome. Repository/GitHub/release workflow packs and environment/IDE/container/AI adapters support it without -becoming equal product pillars. Ubuntu/Debian source-checkout runtime and -apt-backed setup support are implemented, while broader Linux distribution -support remains deliberately narrow and Windows is not currently in scope. +becoming equal product pillars. + +### Current Platform Contract + +Ubuntu/Debian source-checkout runtime and apt-backed setup support are +implemented. Broader Linux distribution support remains deliberately narrow and +Windows is not currently in scope. The local workspace agent brief now summarizes repository readiness for a handoff, while onboarding, diagnostics, privacy-conscious history reports, and @@ -194,7 +198,7 @@ The best adoption path is evidence-driven: Base can become much larger, but the larger possibility is not "put every tool inside Base." The larger possibility is to make readiness and operating context -portable within a project, from a single repository to a repo set, without +portable within a project, from a single repository to a repository set, without absorbing the tools that prepare, build, or host those repositories. ### 2026-07-30 / Single-repository positioning @@ -215,9 +219,6 @@ The review also sharpened the near-term adoption risks. Immediate action items: -- Ubuntu/Debian runtime and apt-backed setup support have since shipped. The - remaining expansion boundary is broader Linux-family, WSL, or Windows support - and external adoption evidence; do not generalize beyond the tested contract. - Semantic onboarding and transferable readiness/handoff evidence are the strongest moat candidate. Local workspace manifests and explicit canonical manifest sync support that outcome, but repository-set materialization alone @@ -280,8 +281,6 @@ not a rewrite of historical releases. Remaining risks should stay issue-backed rather than becoming a parallel backlog here: -- The first Linux target in #562 has since shipped for Ubuntu/Debian. Broader - Linux families, WSL, and Windows still require separate support contracts. - Dev Container and Nix bridges should remain export/bridge work from Base manifests, not a replacement for those ecosystems; this is tracked in #876. - A local dashboard is still plausible, but should follow durable observability @@ -294,14 +293,21 @@ backlog here: Maintainability is the refreshed watchlist. The current file-size pressure is not in the reusable Bash standard library anymore; #873 documents why -single-file shell-library standards remain intentional. The more important -ownership pressure is in command orchestration files: `repo.sh` is roughly -3,400 lines, `setup_common.sh` is roughly 2,170 lines, `repo.bats` is roughly -1,730 lines, and `gh.bats`, `base_projects/engine.py`, and -`base_github_projects/engine.py` are all around the 1,000-line mark. The right -response is not an abstract split-everything campaign. Reduce ownership where a -stable subdomain is visible, keep tests near behavior, and use #929 for the -known `setup_common.sh` ownership-reduction path. +single-file shell-library standards remain intentional. Keep the watchlist +live instead of hardcoding line counts; inspect the current ownership pressure +with: + +```bash +wc -l \ + cli/bash/commands/basectl/subcommands/repo.sh \ + cli/bash/commands/basectl/subcommands/setup_common.sh \ + cli/bash/commands/basectl/tests/repo.bats \ + cli/bash/commands/basectl/tests/gh.bats +``` + +The right response is not an abstract split-everything campaign. Reduce +ownership where a stable subdomain is visible, keep tests near behavior, and +use #929 for the known `setup_common.sh` ownership-reduction path. ### 2026-06-25 / 1.2.0 Product Review Delta @@ -314,7 +320,7 @@ The strongest shipped signal is that Base now has a more durable review and workflow loop around itself: - `basectl workspace init` makes a workspace repository the entry point for - cloning and materializing the declared repo set. + cloning and materializing the declared repository set. - `basectl prompt list` and `basectl prompt product-self-review` make repo-owned prompts inspectable and repeatable instead of private chat-only process. @@ -341,8 +347,6 @@ organizational-impact assessment. Current watchlist for the next release line: -- Ubuntu/Debian support from #562 has since shipped; keep broader Linux, WSL, - and Windows claims separate and evidence-backed. - Command history should earn user-facing reports before a local dashboard becomes product surface. - Artifact support should stay Base-managed and manifest-explicit until real @@ -393,9 +397,6 @@ Current watchlist for the next release line: - Keep the clean macOS install checklist honest by automating safe repeatable steps where possible and explicitly preserving manual-only boundaries where host mutation or real Homebrew installation is required. -- Ubuntu/Debian support from #562 has since shipped. Treat broader Linux - families, WSL, and Windows as separate expansion decisions with their own - evidence and support contracts. - Treat remaining ownership pressure in large shell command modules, Project engines, and broad BATS files as issue-backed maintainability work rather than as a reason to reposition the product. @@ -436,9 +437,6 @@ organizational-impact assessment. Current watchlist for the next release line: -- Keep Ubuntu/Debian claims precise: source-checkout runtime and apt-backed setup - are real, but broader Linux families, WSL, and Windows still need separate - support contracts before public claims expand. - Use the shipped privacy-conscious history report as handoff evidence while keeping the broader #1562 bundle local, redacted, and explicit about missing data. @@ -539,8 +537,6 @@ Watchlist recorded at the 1.7.0 review: explicitly separate until the latter is actually shipped. - Validate the readiness and handoff wedge with external polyrepo design partners before expanding Base's feature surface (#1616). -- Keep Ubuntu/Debian claims precise and treat broader Linux, WSL, and Windows as - separate support-contract decisions. - Continue issue-backed ownership reduction and preserve adapter boundaries as new IDE, container, AI, and environment requests arrive. @@ -590,8 +586,6 @@ Current watchlist for the next release line: #1562 explicitly separate until the latter is actually shipped. - Validate the readiness and handoff wedge with external polyrepo design partners before expanding Base's feature surface (#1616). -- Keep Ubuntu/Debian claims precise and treat broader Linux, WSL, and Windows - as separate support-contract decisions. - Continue issue-backed ownership reduction and preserve adapter boundaries as new IDE, container, AI, environment, and repository-workflow requests arrive. diff --git a/docs/product-requirements.md b/docs/product-requirements.md index 52b93d9d..573c105c 100644 --- a/docs/product-requirements.md +++ b/docs/product-requirements.md @@ -19,7 +19,7 @@ For execution tracking, use GitHub Issues and the workflow in ## Product Thesis Base is a local operating contract for developers and platform engineers who -work across multiple independent Git repositories. It should make the repo set +work across multiple independent Git repositories. It should make the repository set understandable, locally ready, explicitly trusted, onboardable, and transferable without forcing a monorepo or taking project behavior away from its owning repository. @@ -217,19 +217,8 @@ Base should help a target user answer one question at each step: ## Non-Goals -Base should not become: - -- a general tool version manager; -- an automatic directory-based environment loader; -- a full dotfile manager; -- a generic task runner; -- a generic multi-repository checkout, sync, or command fan-out manager; -- a full reproducible package manager or environment solver; -- a local services platform; -- a container runtime; -- a hosted agent runtime, session-transfer service, or provider upload system; -- a replacement for GitHub CLI, IDEs, Homebrew, `mise`, uv, Docker, Nix, - Devbox, Dev Containers, `just`, Taskfile, or project-owned build systems. +Base's canonical non-goals are maintained in +[What Base Is Not](tool-boundaries.md#what-base-is-not). Base can learn from and integrate with those tools. It should not absorb their complete domains. @@ -286,7 +275,7 @@ Use technical docs for implementation detail: behavior. - [Runtime Environment](runtime-environment.md) owns Base-managed variables and mutability rules. -- [Workspace Manifest](workspace-manifest.md) owns the team-shared repo-set +- [Workspace Manifest](workspace-manifest.md) owns the team-shared repository set contract. - [Python Manifest Section](python-manifest.md) owns Python and uv manifest behavior. diff --git a/docs/technical-overview.md b/docs/technical-overview.md index c80b031e..65ad663f 100644 --- a/docs/technical-overview.md +++ b/docs/technical-overview.md @@ -8,7 +8,7 @@ Last reviewed: 2026-08-15 **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 +monorepo, Base makes the repository set understandable, locally ready, explicitly trusted, onboardable, and transferable through one inspectable CLI contract. Its durable product loop is: @@ -30,7 +30,7 @@ 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 gives the repo set a common, inspectable operating contract: +It gives the repository set a common, inspectable operating contract: 1. **Inventory** — identify participating repositories and their declarations. 2. **Prepare** — reconcile the tools and environments those declarations need. @@ -66,9 +66,12 @@ them by scanning the workspace root. | Static analysis | ShellCheck, Pylint, Bandit, pip-audit | | CI | GitHub Actions (tests, lint, skills) | -## Architecture: Three Layers +## Shell Environment Architecture: Three Layers -**Layer 1 — Dotfile integration** (`basectl update-profile`) +These are shell environment layers, not the product responsibility tiers +described in the architecture reference. + +**Shell Layer 1 — Dotfile integration** (`basectl update-profile`) Manages small marked sections in `~/.bash_profile`, `~/.bashrc`, `~/.zprofile`, and `~/.zshrc`. Adds `$BASE_HOME/bin` to `PATH`. Never takes over whole dotfiles. @@ -80,7 +83,7 @@ Markers look like: # <<< base: bashrc managed <<< ``` -**Layer 2 — Base runtime** (`base_init.sh`, sourced on every `basectl` invocation) +**Shell Layer 2 — Base runtime** (`base_init.sh`, sourced on every `basectl` invocation) Exports `BASE_HOME`, `BASE_BIN_DIR`, `BASE_BASH_LIB_DIR`, `BASE_BASH_LIBS_DIR`, `BASE_BASH_LIBS_SOURCE`, `BASE_OS`, `BASE_PLATFORM`, @@ -91,7 +94,7 @@ library root. Sets up The standalone install path and post-migration contract for those reusable libraries are documented in [Base Bash Libraries](base-bash-libs.md). -**Layer 3 — Project environment** (`basectl activate `) +**Shell Layer 3 — Project environment** (`basectl activate `) Spawns a Bash runtime shell, sets `BASE_PROJECT`, applies the project runtime route, runs `activate.source` scripts declared in the manifest, and updates the diff --git a/docs/tool-boundaries.md b/docs/tool-boundaries.md index c2aac9c6..19b9d6eb 100644 --- a/docs/tool-boundaries.md +++ b/docs/tool-boundaries.md @@ -42,6 +42,8 @@ startup, workspace, repository, and release commands it ships. Those supporting surfaces are not evidence that generic machine convergence or multi-repository management is unique to Base. +## What Base Is Not + Base gets weaker when it drifts into becoming any of these: - a general tool version manager @@ -49,9 +51,18 @@ Base gets weaker when it drifts into becoming any of these: - a full dotfile manager - a generic task runner - a full reproducible package manager or environment solver +- a broadly cross-platform runtime; macOS and Ubuntu/Debian are the current + support contract, while broader Linux, WSL, and Windows need separate decisions - a generic multi-repository inventory, synchronization, or command fan-out manager - a multi-VCS client or revision-controlled source-tree materializer +- a local services platform or container runtime +- a hosted agent runtime, live session-transfer service, or provider upload + system +- a second authority for `mani.yaml`, `.repos`, Repo manifests, or `west.yml` +- a replacement for GitHub CLI, IDEs, Homebrew, `mise`, uv, Docker, Nix, + Devbox, Dev Containers, `just`, Taskfile, or project-owned build systems +- a solution for every language runtime, project edge case, or container workflow ## Adapter Quality Bar @@ -747,17 +758,8 @@ trust, lifecycle guidance, onboarding, and portable handoff evidence. ### Base should explicitly avoid becoming -- another polyglot version manager -- another `cd`-triggered environment tool -- another general task runner -- another broad dotfile manager -- another reproducible package manager or dependency solver -- another generic multi-repository inventory, sync, status, or command runner -- a multi-VCS client -- a revision-pinned source-tree materializer or manifest resolution engine -- a second authority for `mani.yaml`, `.repos`, Repo manifests, or `west.yml` -- an agent runtime, hosted session-sharing service, sandbox, or provider-policy - engine +See the canonical [What Base Is Not](#what-base-is-not) list above. This section +does not maintain a second non-goals list. ## What This Means for Future Base Design diff --git a/docs/why-base.md b/docs/why-base.md index 26a9296d..f7771969 100644 --- a/docs/why-base.md +++ b/docs/why-base.md @@ -6,7 +6,7 @@ Last reviewed: 2026-07-30 Base is a local operating contract for developers and platform engineers who need repeatable project readiness and handoff, whether their work lives in one repository or spans multiple independent Git repositories. It makes a project -or participating repo set understandable and locally ready without forcing a +or participating repository set understandable and locally ready without forcing a monorepo or taking project-specific behavior away from the repositories that own it. @@ -44,7 +44,7 @@ external tools and project declarations it orchestrates. | Prepare | `basectl setup`, workspace init/clone/pull/configure, and project-owned adapters prepare the declared local state through explicit commands. | | Verify | `basectl check` and `basectl doctor`, including workspace forms, report readiness with JSON where supported and stable doctor finding IDs. | | Trust | `basectl trust` keeps manifest-declared project execution behind explicit local approval while leaving inspection paths available. | -| Onboard | `basectl onboard` guides first Base setup; `basectl workspace onboarding` gives a read-only first-day repo-set summary. | +| Onboard | `basectl onboard` guides first Base setup; `basectl workspace onboarding` gives a read-only first-day repository set summary. | | Hand off | `basectl workspace agent-brief` summarizes repository readiness; diagnostics, history reports, and context exports provide deeper local evidence. | The workspace-level brief is shipped, but Base does not yet compose issue, @@ -74,7 +74,7 @@ packages: - A small opt-in contract for independent repositories through `base_manifest.yaml`. - Inventory, workspace onboarding, and agent-brief views that do not require - cloning or setup to inspect repo-set and handoff state. + cloning or setup to inspect repository set and handoff state. - Human-readable and machine-readable readiness checks through `check`, `doctor`, workspace reports, and stable finding IDs. - Explicit manifest-command trust instead of silently executing project-owned diff --git a/docs/workspace-manifest.md b/docs/workspace-manifest.md index 98db8d72..76d1320d 100644 --- a/docs/workspace-manifest.md +++ b/docs/workspace-manifest.md @@ -38,7 +38,7 @@ activation, commands, tests, demo, IDE requirements, and health declarations. A workspace manifest is a team-shared contract that lists repositories that should exist in a workspace. It answers "which repos belong together?", not -"how does each repo set itself up?" +"how does each repository prepare itself?" An expected repository is listed in the workspace manifest. It may or may not exist locally yet.