From eaf5cee90d80d47f982848c8b119348461ec2cb7 Mon Sep 17 00:00:00 2001 From: Ramesh Padmanabhaiah Date: Tue, 9 Jun 2026 22:27:29 -0700 Subject: [PATCH] Add Base newcomer presentation docs --- CHANGELOG.md | 2 + README.md | 1 + docs/README.md | 10 + docs/presentations/README.md | 58 ++++ .../base-newcomer-orientation.md | 285 ++++++++++++++++++ 5 files changed, 356 insertions(+) create mode 100644 docs/presentations/README.md create mode 100644 docs/presentations/base-newcomer-orientation.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 96e27c5..86383e4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,8 @@ and Base versions are tracked in the repo-root `VERSION` file. Releases, including post-publish Homebrew handoff reporting. - Added read-only `basectl release check|plan|notes` commands backed by manifest-owned release metadata. +- Added a text-first Base newcomer orientation deck and documented the optional + PDF/PPTX export path. - Added opt-in project Git `origin` reachability diagnostics with `basectl check|doctor --remote-network`. - Added an explicit `ai` prerequisite profile for Codex CLI and Claude Code diff --git a/README.md b/README.md index 597ca5b..9b0ab3a 100644 --- a/README.md +++ b/README.md @@ -859,6 +859,7 @@ feature designs, and ecosystem boundary decisions. Key starting points: - [FAQ](FAQ.md) +- [Base Newcomer Orientation](docs/presentations/base-newcomer-orientation.md) - [Architecture](docs/architecture.md) - [Clean macOS Install Validation](docs/macos-install-validation.md) - [Execution Model](docs/execution-model.md) diff --git a/docs/README.md b/docs/README.md index 1f130d6..cb06d09 100644 --- a/docs/README.md +++ b/docs/README.md @@ -14,6 +14,9 @@ worktree-based PR trains, see [GitHub Workflow](github-workflow.md). For release preparation, tagging, GitHub Releases, and the Homebrew tap update, see [Release Process](release-process.md). +For self-guided or live walkthrough material, see +[Presentations](presentations/README.md). + ## Naming Convention Use stable topic names for documentation files: @@ -51,6 +54,13 @@ reference. The filename should answer "what is this about?" - [Tool Boundaries](tool-boundaries.md) records ecosystem decisions for tools such as `mise`, `direnv`, Homebrew, IDEs, Docker, and dotfile managers. +## Presentations + +- [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. + ## Feature And Boundary Documents - [IDE Bootstrapping](ide-bootstrapping.md) covers project IDE manifests, diff --git a/docs/presentations/README.md b/docs/presentations/README.md new file mode 100644 index 0000000..f4d661d --- /dev/null +++ b/docs/presentations/README.md @@ -0,0 +1,58 @@ +# Base Presentations + +This directory holds text-first presentation sources for Base. Presentations are +orientation material, not canonical product references. When slide content needs +implementation detail, link to the README or focused documentation page instead +of duplicating the reference text. + +## Decks + +- [Base Newcomer Orientation](base-newcomer-orientation.md) introduces Base as + a workspace control plane for multi-repo development. + +## Source Of Truth + +The markdown file is the canonical deck source. Generated PDF or PPTX files are +not committed by default because they are derived artifacts and can drift from +the checked-in source. + +Attach generated files to a release, workshop note, or external sharing surface +when needed. If generated artifacts are ever committed later, the PR should +state why, name the exact source revision, and update this policy. + +## Export Path + +Use Marp CLI when a shareable PDF or PPTX is needed. The commands below generate +artifacts from the checked-in markdown source without adding Marp to Base's +default setup path. + +```bash +mkdir -p /tmp/base-presentations + +npx --yes @marp-team/marp-cli \ + docs/presentations/base-newcomer-orientation.md \ + --pdf \ + --output /tmp/base-presentations/base-newcomer-orientation.pdf + +npx --yes @marp-team/marp-cli \ + docs/presentations/base-newcomer-orientation.md \ + --pptx \ + --output /tmp/base-presentations/base-newcomer-orientation.pptx +``` + +For repeatable workshop or release exports, record the Marp CLI version used: + +```bash +npx --yes @marp-team/marp-cli --version +``` + +## Validation + +Ordinary documentation validation does not require export tooling: + +```bash +git diff --check +``` + +When export tooling is available, smoke-test the export commands before sharing +generated files and inspect the resulting PDF or PPTX manually. diff --git a/docs/presentations/base-newcomer-orientation.md b/docs/presentations/base-newcomer-orientation.md new file mode 100644 index 0000000..900196a --- /dev/null +++ b/docs/presentations/base-newcomer-orientation.md @@ -0,0 +1,285 @@ +--- +marp: true +paginate: true +--- + +# Base Newcomer Orientation + +Workspace control plane for multi-repo development + +Canonical product details live in the README and focused docs. This deck is an +orientation path for GitHub readers and live walkthroughs. + +--- + +## The Problem + +Most real engineering work is not one repository. + +A developer may need: + +- shared tooling checked out beside project repositories +- consistent setup across machines +- project-specific tests and tasks +- diagnostics that explain what is missing +- shell activation without copying private dotfile logic into every repo + +Base gives that workspace a common operating layer. + +--- + +## What Base Is + +Base is a workspace control plane. + +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 does not turn sibling repositories into a monorepo. + +Read more: [Architecture](../architecture.md) + +--- + +## What Base Owns + +Base owns the cross-repo workflow surface: + +- workspace discovery +- first-mile bootstrap +- Base-managed shell runtime +- project virtualenv location +- manifest parsing +- setup/check/doctor/test/run/demo command routing +- standard repo and GitHub workflow helpers +- guarded release assistant commands + +Read more: [Execution Model](../execution-model.md) + +--- + +## What Projects Still Own + +Project repositories keep authority over product behavior: + +- source code and services +- language-native package files +- tests and build tasks +- project installers +- demos and walkthrough scripts +- Brewfiles, mise configs, and service definitions +- repo-specific contribution rules + +Base orchestrates these contracts. It does not replace them. + +Read more: [Tool Boundaries](../tool-boundaries.md) + +--- + +## First-Mile Bootstrap + +Base starts before the developer has a working Base environment. + +On macOS, `bootstrap.sh` handles the first mile: + +```bash +curl -fsSL https://raw.githubusercontent.com/codeforester/base/master/bootstrap.sh | bash +``` + +It installs or checks the prerequisites needed to hand off to `basectl setup`. +Users can choose source checkout mode or Homebrew install mode explicitly. + +Read more: [First-Mile Bootstrap](../bootstrap.md) + +--- + +## Install Choices + +Source checkout mode is best for contributors and local Base development. + +Homebrew mode is best for users who want Base installed as a tool outside their +project workspace. + +Both modes converge on the same daily command surface: + +```bash +basectl setup +basectl update-profile +basectl check +basectl doctor +``` + +Read more: [Clean macOS Install Validation](../macos-install-validation.md) + +--- + +## The Daily Loop + +After installation, the common workflow is: + +```bash +basectl projects list +basectl setup +basectl check +basectl doctor +basectl test +basectl run +basectl demo +basectl activate +``` + +The goal is one predictable loop across many repositories. + +--- + +## Project Discovery + +Base scans a workspace root and finds repositories with `base_manifest.yaml`. + +The workspace root usually comes from `~/.base.d/config.yaml`: + +```yaml +workspace: + root: ~/work +``` + +Workspace manifests can add expected repositories to the same view so teams can +distinguish missing repos from broken repos. + +Read more: [Workspace Manifest](../workspace-manifest.md) + +--- + +## The Manifest Contract + +`base_manifest.yaml` is the small project contract Base reads. + +```yaml +schema_version: 1 + +project: + name: example + +brewfile: Brewfile +mise: .mise.toml + +test: + mise: test + +commands: + dev: mise run dev +``` + +The manifest says what Base should orchestrate, not every product detail. + +--- + +## Setup, Check, Doctor + +The setup and diagnostic commands answer different questions. + +`basectl setup ` prepares Base and project-declared artifacts. + +`basectl check ` gives a concise pass/fail readiness signal. + +`basectl doctor ` explains findings and fix commands. + +Machine-readable JSON output exists where CI or tools need structured results. + +Read more: [Doctor Finding IDs](../doctor-findings.md) + +--- + +## Test, Run, Demo, Activate + +Base delegates work back to the project: + +- `basectl test ` runs the declared test contract +- `basectl run ` runs named manifest commands +- `basectl demo ` runs the project-owned walkthrough script +- `basectl activate ` opens a project shell with the Base runtime + +Projects stay responsible for what those commands actually do. + +Read more: [Project Demo Workflow](../project-demo-workflow.md) + +--- + +## Base Self-Demo And Reference Project + +There are two demo layers: + +- `basectl demo base -- --non-interactive` demonstrates Base itself +- `codeforester/base-demo` demonstrates a normal Base-managed project + +Clone `base-demo` beside Base to inspect a small reference project: + +```bash +git clone https://github.com/codeforester/base-demo.git +basectl setup base-demo +basectl demo base-demo +``` + +Read more: [Base-managed demo project](../base-managed-demo-project.md) + +--- + +## CI Posture + +`basectl ci` is the non-interactive CI entry point. + +```bash +basectl ci setup --format json +basectl ci check --format json +basectl ci doctor --format json +``` + +It sets CI-safe defaults, avoids prompts, and reuses the same manifest and +diagnostic paths as local development. + +Read more: [`basectl ci`](../basectl-ci.md) + +--- + +## Release Posture + +Base releases are explicit ceremonies. + +`basectl release` validates release metadata, prints the release plan, extracts +release notes, and publishes guarded GitHub release artifacts. + +Homebrew tap updates remain a separate handoff after the Base tag and GitHub +Release exist. The 1.0 upgrade rehearsal records the consumer upgrade proof. + +Read more: [Release Process](../release-process.md) + +--- + +## Contributor Workflow + +Base work normally follows an issue-backed PR train: + +1. pick or create the GitHub issue +2. create a branch/worktree from `origin/master` +3. make the narrow change +4. run the relevant validation +5. open the PR with issue closure text and validation evidence +6. merge when checks pass and clean up the worktree + +Read more: [GitHub Workflow](../github-workflow.md) + +--- + +## Where To Go Next + +Start with: + +- [README](../../README.md) for product overview and first-run commands +- [Documentation Map](../README.md) for the full doc set +- [Architecture](../architecture.md) for product direction +- [Tool Boundaries](../tool-boundaries.md) for ownership boundaries +- [First-Mile Bootstrap](../bootstrap.md) for install behavior +- [Project Demo Workflow](../project-demo-workflow.md) for demos + +Then clone `base-demo` beside Base and run the daily loop.