basefoundry · codeforester · Jul 1, 2026 · Jul 1, 2026
@@ -37,6 +37,21 @@ Common first-run and product questions are answered in [FAQ.md](FAQ.md).
 Contributions should follow [CONTRIBUTING.md](CONTRIBUTING.md). Release notes
 are tracked in [CHANGELOG.md](CHANGELOG.md).
 
+## Source Control And Forge Support
+
+Base assumes Git. Mercurial, Perforce, Subversion, and other non-Git SCMs are
+out of scope.
+
+Base is GitHub-primary rather than forge-independent. GitHub is the only
+first-class forge automation target today for repository creation,
+configuration, Issues, pull requests, Projects, Actions intake, and release
+publishing. A GitLab, Bitbucket, internal Git, or local Git repository can
+still use Base's local project loop once it is checked out locally and declares
+`base_manifest.yaml`.
+
+See [Source Control And Forge Support](docs/source-control-and-forge-support.md)
+for the command-by-command compatibility contract and non-GitHub Git workflow.
+
 ## Start Here
 
 ### Choose An Install Path
@@ -491,11 +506,14 @@ repositories are errors, missing optional repositories are warnings, and
 Base-managed projects outside the manifest stay visible as warnings.
 
 Use `basectl workspace clone --manifest <path>`, or configure
-`workspace.manifest`, to materialize the missing required repositories from that
-manifest. The command keeps existing repositories visible, delegates each
-repository operation to `basectl repo clone`, and supports `--dry-run` for a
-no-write preview. Optional repositories are reported but skipped unless
-`--include-optional` is supplied.
+`workspace.manifest`, to materialize the missing required GitHub repositories
+from that manifest. The command keeps existing repositories visible, delegates
+each repository operation to `basectl repo clone`, and supports `--dry-run` for
+a no-write preview. Optional repositories are reported but skipped unless
+`--include-optional` is supplied. Workspace manifests may list non-GitHub Git
+URLs for reporting, but automatic materialization through `workspace clone` is
+GitHub-only today; clone GitLab, Bitbucket, internal Git, or local repositories
+with ordinary Git first, then let Base discover the local checkout.
 
 Use `basectl workspace init <workspace-source>` for first-run bootstrap from a
 workspace configuration repository. The source can be a local path, GitHub URL,
@@ -555,6 +573,10 @@ Without `--path`, `repo clone` writes to `<workspace.root>/<repo>`, and
 URL without touching the filesystem. Existing matching checkouts are treated as
 already satisfied; conflicting destinations fail with guidance.
 
+`repo clone` and `repo configure` are GitHub automation surfaces. For
+non-GitHub Git repositories, use the forge's normal Git clone path and then use
+Base's local project loop from the resulting checkout.
+
 Check and repair the repo baseline with:
 
 ```bash

@@ -55,6 +55,9 @@ reference. The filename should answer "what is this about?"
   manifest contract, command tables, and file locations.
 - [Architecture](architecture.md) describes Base's product direction, command
   model, environment model, manifest shape, and repository conventions.
+- [Source Control And Forge Support](source-control-and-forge-support.md)
+  defines Base's Git-only, GitHub-primary support contract and the expected
+  behavior for non-GitHub Git repositories.
 - [First-Mile Bootstrap](bootstrap.md) documents `bootstrap.sh`, install mode
   selection, handoff commands, and contributor setup.
 - [Clean macOS Install Validation](macos-install-validation.md) defines the

@@ -8,11 +8,14 @@ multiple projects through a single CLI interface. The current implementation sup
 contract is macOS. Linux is a future design target, while Windows support is not in
 scope.
 
-The governing philosophy: **solve your own problem elegantly first**. Base is built for
-a specific workflow — multiple peer GitHub repositories under a shared parent directory,
-each declaring their dependencies through a simple manifest, all managed through a
-unified interface. If it works well for its author, it will work well for others with
-similar constraints.
+The governing philosophy: **solve your own problem elegantly first**. Base is
+built for a specific workflow: multiple peer Git repositories under a shared
+parent directory, each declaring their dependencies through a simple manifest,
+all managed through a unified interface. GitHub is the first-class forge
+automation target today. Non-GitHub Git repositories can still use Base's local
+project loop after they exist locally, but GitHub workflow automation remains
+GitHub-specific. The exact contract lives in
+[Source Control And Forge Support](source-control-and-forge-support.md).
 
 ---
 
@@ -57,8 +60,8 @@ need Base's orchestration model.
 
 ## Repository Structure
 
-Base is a public GitHub repository. All projects managed by Base are also GitHub
-repositories, checked out as peers under a shared parent directory:
+Base is a public GitHub repository. The primary dogfood workspace is a set of
+GitHub repositories checked out as peers under a shared parent directory:
 
 ```
 ~/work/              ← shared workspace root
@@ -68,8 +71,10 @@ repositories, checked out as peers under a shared parent directory:
   banyanlabs/        ← peer project with base_manifest.yaml
 ```
 
-Base discovers peer repositories by scanning the workspace root for repositories
-that contain `base_manifest.yaml`.
+Base discovers peer repositories by scanning the workspace root for Git
+repositories that contain `base_manifest.yaml`. The local project loop does not
+require the remote to be hosted on GitHub. Repository creation, configuration,
+issue, pull-request, Project, and release automation do require GitHub today.
 
 ---
 

@@ -13,6 +13,19 @@ syntax.
 `--config`, `--environment`, and `--keep-temp` are private to Python package
 execution and are rejected by `basectl`.
 
+## Source Control And Forge Boundary
+
+Base assumes Git as the source-control system. Non-Git SCMs such as Mercurial,
+Perforce, and Subversion are out of scope.
+
+Base is GitHub-primary today. Local project commands work for non-GitHub Git
+repositories once they are checked out locally and declare `base_manifest.yaml`.
+Repository creation, cloning, configuration, issue, pull-request, Project, and
+release automation are GitHub-specific unless a command explicitly says
+otherwise. See
+[Source Control And Forge Support](source-control-and-forge-support.md) for the
+full compatibility contract.
+
 ## Install And Bootstrap
 
 | Command | What it does | Important flags |
@@ -67,13 +80,17 @@ inspect the resolved command contract first.
 | `basectl workspace status` | Show read-only workspace project status and latest recorded project check dates. Uses `workspace.manifest` from user config unless `--manifest` is supplied. | `--workspace <path>`, `--manifest <path>`, `--format <text\|json>` |
 | `basectl workspace check` | Run read-only checks across workspace projects. Uses `workspace.manifest` from user config unless `--manifest` is supplied. | `--workspace <path>`, `--manifest <path>`, `--format <text\|json>` |
 | `basectl workspace doctor` | Run read-only diagnostics across workspace projects. Uses `workspace.manifest` from user config unless `--manifest` is supplied. | `--workspace <path>`, `--manifest <path>`, `--format <text\|json>` |
-| `basectl workspace clone` | Clone or validate expected repositories from a workspace manifest. Uses `workspace.manifest` from user config unless `--manifest` is supplied. | `--workspace <path>`, `--manifest <path>`, `--include-optional`, `--dry-run` |
+| `basectl workspace clone` | Clone or validate expected repositories from a workspace manifest. Missing-repository materialization is GitHub-only today because this path delegates to `repo clone`. Uses `workspace.manifest` from user config unless `--manifest` is supplied. | `--workspace <path>`, `--manifest <path>`, `--include-optional`, `--dry-run` |
 | `basectl workspace pull` | Explicitly fetch and validate a canonical workspace manifest source before updating the local workspace manifest. Uses `workspace.manifest_source` and `workspace.manifest` from user config unless flags are supplied. | `--source <url-or-path>`, `--manifest <path>`, `--dry-run` |
 | `basectl workspace init <workspace-source>` | Initialize a workspace from a workspace configuration repository, update local workspace config, and optionally materialize member repositories. | `--owner <owner>`, `--path <path>`, `--workspace <path>`, `--manifest <path>`, `--include-optional`, `--dry-run` |
 | `basectl workspace configure` | Apply the existing `repo configure` repair path across discovered Base-managed workspace repositories or an explicit workspace manifest. Skips missing, non-Base-managed, or non-GitHub repos and continues after per-repo failures. | `--workspace <path>`, `--manifest <path>`, `--dry-run` |
 
 ## Repository And GitHub Workflow
 
+This section is intentionally GitHub-specific except for local baseline
+inspection. Use ordinary Git to clone non-GitHub repositories, then use the
+daily project loop commands from the local checkout.
+
 | Command | What it does | Important flags |
 |---|---|---|
 | `basectl repo init <name>` | Create a Base-managed repository baseline, including `.github/base-project.yml`, and optionally create/configure the GitHub repo. | `--path <path>`, `--repo <owner/name>`, `--description <text>`, `--copyright-holder <name>`, `--public`, `--private`, `--pr`, `--project <title>`, `--project-owner <login>`, `--project-schema <schema>`, `--copy-project-fields-from <title>`, `--initiative-option <name>`, `--no-configure`, `--no-project`, `--no-protect-default-branch`, `--dry-run` |

@@ -0,0 +1,115 @@
+# Source Control And Forge Support
+
+Base is Git-based and GitHub-primary.
+
+This page is the canonical contract for what that means. It separates the local
+Base project loop, which is mostly forge-neutral once a Git checkout exists,
+from the repository workflow automation that intentionally targets GitHub
+today.
+
+## Support Contract
+
+Base assumes Git as the underlying source-control system.
+
+Supported source-control baseline:
+
+- Git repositories checked out on the local machine.
+- Direct-child repository layouts under a shared workspace root.
+- Project metadata declared through `base_manifest.yaml`.
+- Git remotes hosted by GitHub, GitLab, Bitbucket, an internal Git server, or a
+  local filesystem remote when the command only needs ordinary Git behavior.
+
+Out of scope:
+
+- Mercurial.
+- Perforce.
+- Subversion.
+- Fossil.
+- Other non-Git SCMs.
+
+GitHub is the only first-class forge automation target today. Base can automate
+GitHub repository creation and configuration, GitHub Issues, pull requests,
+Projects, Actions-based intake, and GitHub Releases. It does not currently
+provide equivalent automation for GitLab, Bitbucket, Azure DevOps, or other Git
+forges.
+
+## Command Compatibility
+
+| Command area | Non-GitHub Git behavior |
+|---|---|
+| Local project loop: `projects list`, `setup`, `check`, `doctor`, `activate`, `run`, `test`, `build`, `demo`, `export-context` | Supported once the repository exists locally and has `base_manifest.yaml`. These commands use local files, project manifests, and ordinary process execution. |
+| Git update: `update [project]` | Supported for ordinary Git checkouts when the repo is on its default branch and the worktree is clean enough for Base's update guardrails. |
+| Remote diagnostics: `check [project]`, `doctor [project]` | Supported. Non-GitHub remotes are reported as non-GitHub providers and do not require GitHub CLI authentication. Optional network checks use Git reachability rather than forge APIs. |
+| Workspace reports: `workspace status`, `workspace check`, `workspace doctor` | Supported. Workspace manifests can list GitLab, Bitbucket, internal Git, or local repository URLs as metadata for reporting. |
+| Workspace manifest refresh: `workspace pull` | Supported for local paths, `file://` URLs, and raw `https://` manifest files. It updates the manifest file only; it does not clone or mutate project repositories. |
+| Repository materialization: `repo clone`, `workspace clone`, `workspace init` when cloning repositories | GitHub-only today. These paths delegate to GitHub repository specs and should fail clearly when asked to materialize unsupported non-GitHub repositories. |
+| Repository baseline: `repo init`, `repo check` | Local baseline files can be created and checked without GitHub, but the standard Base baseline is GitHub-flavored: `.github` workflows, pull request template, and Project intake files are part of that contract. |
+| Repository automation: `repo configure`, `workspace configure` | GitHub-specific. `workspace configure` skips non-GitHub repositories, while `repo configure` requires an explicit or inferable GitHub repository. |
+| GitHub workflow: `gh ...` | GitHub-specific by name and behavior. |
+| Release publishing: `release publish` | GitHub Release publishing today. Release readiness commands also expect the manifest's current GitHub release metadata. |
+| Documentation shortcut: `docs` | Opens the GitHub-hosted Base documentation entry point. |
+
+## Non-GitHub Git Workspaces
+
+A GitLab, Bitbucket, internal Git, or local Git repository can still use Base's
+local control-plane loop:
+
+1. Clone the repository with the normal Git tooling for that forge.
+2. Place the checkout under `workspace.root`, or pass `--workspace <path>` when
+   inspecting a different root.
+3. Add a valid `base_manifest.yaml`.
+4. Use `basectl projects list`, `basectl setup <project>`,
+   `basectl check <project>`, `basectl doctor <project>`,
+   `basectl test <project>`, `basectl run <project> <command>`, and related
+   local project commands.
+
+Workspace manifests may include non-GitHub Git URLs so reports can describe
+the expected repository set. Today, those URLs are metadata for read-only
+workspace reporting unless the materialization command explicitly documents
+support for that URL shape. If a missing GitLab or Bitbucket repository needs
+to be cloned, clone it manually with Git, then let Base discover and diagnose
+the local checkout.
+
+Avoid these commands unless GitHub is intentionally part of the repository
+workflow:
+
+- `basectl repo clone`
+- `basectl repo configure`
+- `basectl workspace clone`
+- `basectl workspace init` when it must clone repositories
+- `basectl workspace configure`
+- `basectl gh ...`
+- `basectl release publish`
+
+## Future Forge Support
+
+GitLab and Bitbucket are viable future support targets, but they should not be
+added speculatively. The current product strategy is to prove the GitHub-first
+model through real adoption before Base grows provider adapters.
+
+If adoption proves the need, the right direction is a narrow forge-provider
+boundary rather than scattered conditional logic. Likely adapter seams include:
+
+- remote provider detection
+- repository clone and creation
+- issue and merge-request or pull-request workflows
+- project or board metadata
+- release publishing
+- CI or workflow intake
+
+Each provider should be added because a real workspace needs it, not because
+Base wants to present itself as generally forge-independent.
+
+## Clean Failure Expectations
+
+GitHub-specific commands should not make a non-GitHub Git repository look
+broken. They should either:
+
+- skip that repository with an explicit non-GitHub explanation,
+- fail with a direct "GitHub-only today" message, or
+- point the user to the manual Git workflow when Base can still operate on the
+  resulting local checkout.
+
+The user should be able to distinguish "this repository is unhealthy" from
+"this command is a GitHub automation surface and this repository uses another
+forge."
@@ -0,0 +1,103 @@
+# Forge Support Boundaries Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Document Base's Git-only and GitHub-primary support contract so non-GitHub Git users get predictable guidance instead of implicit assumptions.
+
+**Architecture:** Add one canonical support-boundary page and link existing command and workspace docs to it. Keep this PR documentation-focused; defer provider adapters or new GitLab/Bitbucket behavior until GitHub-first adoption proves the need.
+
+**Tech Stack:** Markdown, existing docs map, existing Base validation commands.
+
+---
+
+### Task 1: Add The Canonical Support Contract
+
+**Files:**
+- Create: `docs/source-control-and-forge-support.md`
+- Modify: `docs/README.md`
+- Modify: `docs/architecture.md`
+
+- [ ] **Step 1: Create the support-boundary page**
+
+Add `docs/source-control-and-forge-support.md` with these sections:
+
+```markdown
+# Source Control And Forge Support
+
+## Support Contract
+
+## Command Compatibility
+
+## Non-GitHub Git Workspaces
+
+## Future Forge Support
+
+## Clean Failure Expectations
+```
+
+The page must state that Git is required, non-Git SCMs are out of scope, GitHub is first-class today, and GitLab/Bitbucket support is deferred until adoption proves the need.
+
+- [ ] **Step 2: Link the page from the docs map**
+
+Add a Core Documents or Feature And Boundary Documents bullet in `docs/README.md` pointing to the new page.
+
+- [ ] **Step 3: Update architecture wording**
+
+Modify `docs/architecture.md` so the overview keeps the GitHub-primary product loop but points readers to the support-boundary page for exact non-GitHub behavior.
+
+### Task 2: Correct Command And Workspace Documentation
+
+**Files:**
+- Modify: `README.md`
+- Modify: `docs/command-reference.md`
+- Modify: `docs/workspace-manifest.md`
+
+- [ ] **Step 1: Add the product-front-door summary**
+
+Add a short README section explaining that Base is Git-based, GitHub-primary, and still useful for local non-GitHub Git projects through the local command loop.
+
+- [ ] **Step 2: Clarify command-reference categories**
+
+Add a short compatibility note near the command tables in `docs/command-reference.md`, and make GitHub-only commands explicit where the table could otherwise imply forge independence.
+
+- [ ] **Step 3: Fix workspace manifest clone wording**
+
+Adjust `docs/workspace-manifest.md` so `repos[].url` remains generic metadata for reporting, while current `basectl workspace clone` support is documented as GitHub-only when materializing missing repositories.
+
+### Task 3: Validate And Publish
+
+**Files:**
+- Validate all touched docs and existing tests.
+
+- [ ] **Step 1: Run focused docs validation**
+
+Run:
+
+```bash
+env -u BASE_HOME PYTHONPATH=lib/python:cli/python \
+  "$HOME/.base.d/base/.venv/bin/python" -m pytest \
+  tests/test_base_cli_docs.py tests/test_contract_hardening.py -q
+```
+
+Expected: all selected tests pass.
+
+- [ ] **Step 2: Run full Base validation**
+
+Run:
+
+```bash
+env -u BASE_HOME BASE_BASH_LIBS_DIR=/Users/rameshhp/work/base-bash-libs/lib/bash BASE_CACHE_DIR=/private/tmp/base-1344-final ./bin/base-test
+```
+
+Expected: Python suite and Bats/source suite pass.
+
+- [ ] **Step 3: Commit and open the PR**
+
+Commit with:
+
+```bash
+git add README.md docs/README.md docs/architecture.md docs/command-reference.md docs/source-control-and-forge-support.md docs/workspace-manifest.md docs/superpowers/plans/2026-07-01-forge-support-boundaries.md
+git commit -m "Document forge support boundaries"
+```
+
+Push `documentation/1344-20260701-forge-support-boundaries` and open a PR linked to issue `#1344`.