### Install Phase Function Example

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/planning/ROADMAP_INSTALLER_RELIABILITY.md

Demonstrates how to use the `try_step` wrapper within an installation phase function to install various language runtimes. It checks for existing installations before attempting to install.

```bash
install_phase_languages() {
    CURRENT_PHASE_NAME="Language Runtimes"

    # Bun
    if ! command -v bun &>/dev/null;
    then
        try_step "Installing Bun runtime" \
            "acfs_curl https://bun.sh/install | bash" || return 1
    fi

    # Rust
    if ! command -v cargo &>/dev/null;
    then
        try_step "Installing Rust via rustup" \
            "acfs_curl https://sh.rustup.rs | sh -s -- -y" || return 1
    fi

    # UV
    if ! command -v uv &>/dev/null;
    then
        try_step "Installing uv (Python tooling)" \
            "acfs_curl https://astral.sh/uv/install.sh | sh" || return 1
    fi

    # Go
    if ! command -v go &>/dev/null;
    then
        try_step "Installing Go" \
            "install_go_tarball" || return 1
    fi

    return 0
}
```

--------------------------------

### Default Install Example

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/planning/PLAN_TO_HAVE_SINGLE_SOURCE_OF_TRUTH_MANIFEST.md

Installs all modules with `enabled_by_default: true` when no specific flags are provided. This results in a full stack installation.

```bash
./install.sh --yes --mode vibe
```

--------------------------------

### Install Docker CLI

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/audits/manifest-gap-analysis.md

Example manifest entry for installing Docker, including installation and verification commands.

```yaml
- id: cli.docker
  description: Docker container runtime
  install:
    - sudo apt-get install -y docker.io docker-compose-plugin
  verify:
    - docker --version
  tags: [optional, containers]
```

--------------------------------

### Install and Run Website Development Dependencies

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/AGENTS.md

Install project dependencies and start the development server for the website. Use for linting and type checking as well.

```bash
cd apps/web
bun install           # Install dependencies
bun run dev           # Dev server
bun run build         # Production build
bun run lint          # Lint check
bun run type-check    # TypeScript check
```

--------------------------------

### Installation Time by Phase Benchmarks

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/README.md

Typical durations for different phases of the installation process. Note that shell setup and CLI tools can take several minutes.

```markdown
| Phase | Typical Duration |
|---|---|
| User Setup | 10-15s |
| Filesystem | 5-10s |
| Shell Setup | 2-4 min |
| CLI Tools | 3-5 min |
| Languages | 3-5 min |
| Agents | 1-2 min |
| Cloud | 1-2 min |
| Stack | 4-6 min |
| Finalize | 30-60s |
| **Total** | **15-25 min** |
```

--------------------------------

### Example Installation Flow with Interruption and Resume

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/planning/PLAN_TO_HAVE_SINGLE_SOURCE_OF_TRUTH_MANIFEST.md

Demonstrates a typical installation workflow, including interruption and subsequent resumption. It also shows how changing flags like `--only` can reset the plan and state.

```bash
# First run: interrupted after phase 4
./install.sh --mode vibe
# ^C

# Resume: same plan, starts from phase 5
./install.sh --resume

# Changed flags: different plan, starts from beginning
./install.sh --only lang.bun
# Warns: "Previous state.json exists but --only changes the plan. Starting fresh."
```

--------------------------------

### Start NTM Tutorial

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/acfs/onboard/lessons/05_ntm_core.md

Launches the interactive NTM tutorial to guide users through the basics.

```bash
ntm tutorial
```

--------------------------------

### Beginner Default Install Command

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/planning/PLAN_TO_HAVE_SINGLE_SOURCE_OF_TRUTH_MANIFEST.md

Example CLI command for a beginner user performing a default installation using the website wizard. This command bootstraps the repository, validates scripts, and proceeds with a default selection of enabled modules.

```bash
curl -fsSL https://raw.githubusercontent.com/.../install.sh | bash -s -- --yes --mode vibe
```

--------------------------------

### Verified Installer Module Example (Bun)

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/reference/MANIFEST_SCHEMA_VNEXT.md

Defines a module for installing the Bun JavaScript runtime using a verified installer. It specifies the tool, runner, and arguments for installation.

```yaml
- id: lang.bun
  description: Bun JavaScript runtime
  category: lang
  phase: 6
  run_as: target_user
  optional: false
  enabled_by_default: true
  tags: [critical, runtime]
  dependencies:
    - base.system
  verified_installer:
    tool: bun
    runner: bash
    args: []
  installed_check:
    run_as: target_user
    command: "command -v bun"
  install: []  # Empty - handled by verified_installer
  verify:
    - bun --version
```

--------------------------------

### ACFS Installer Script Example

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/planning/PLAN_TO_CREATE_ACFS.md

An example of tasks performed by the ACFS installer script for Milestone 1 (MVP). This includes user creation, shell configuration, and installation of core tools.

```bash
# install.sh
# Creates `ubuntu` user
# Installs zsh + shell config via `~/.acfs`
# Installs tmux + ntm
# Installs cc/cod/gmi dependencies
# Installs basic `onboard`
```

--------------------------------

### Install Gum CLI

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/audits/manifest-gap-analysis.md

Example of how to add the Gum CLI to the manifest, including installation steps and verification.

```yaml
- id: cli.gum
  description: Gum terminal UI toolkit
  install:
    - "Add Charm apt repository"
    - sudo apt-get install -y gum
  verify:
    - gum --version
  tags: [optional, ui]
```

--------------------------------

### Verify PT Installation

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/acfs/onboard/lessons/14_pt.md

Check if PT is installed by running the help command. This is a basic setup verification step.

```bash
pt --help
```

--------------------------------

### Install GitHub CLI

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/audits/manifest-gap-analysis.md

Example of how to add the GitHub CLI to the manifest, specifying installation and verification commands.

```yaml
- id: cli.gh
  description: GitHub CLI
  install:
    - "Add GitHub CLI apt repository or install from distro"
    - sudo apt-get install -y gh
  verify:
    - gh --version
  tags: [recommended]
```

--------------------------------

### Installer Main Function with Resume Logic

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/planning/ROADMAP_INSTALLER_RELIABILITY.md

The main installer function handles initialization, checks for previous installations, and provides an option to resume or start fresh. It uses state management functions to save and load installation progress.

```bash
# At installer start
main() {
    init_state

    # Check for resume scenario
    if [[ ${#COMPLETED_PHASES[@]} -gt 0 ]]; then
        local last_phase="${COMPLETED_PHASES[-1]}"
        log_step "Resume" "Detected previous install (completed phases: 1-$last_phase)"

        if [[ "$YES_MODE" != "true" ]]; then
            if ! confirm_resume;
                log_detail "Starting fresh install"
                COMPLETED_PHASES=()
                CURRENT_PHASE=0
                save_state
            fi
        fi
    fi

    # Run all phases (skipping completed ones)
    run_phase 1 "User Normalization" install_phase_1
    run_phase 2 "APT Packages" install_phase_2
    run_phase 3 "Shell Setup" install_phase_3
    # ... etc
}

confirm_resume() {
    if [[ "$HAS_GUM" == "true" ]]; then
        gum confirm "Resume from phase $((${COMPLETED_PHASES[-1]} + 1))?"
    else
        read -p "Resume from phase $((${COMPLETED_PHASES[-1]} + 1))? [Y/n] " -r
        [[ -z "$REPLY" || "$REPLY" =~ ^[Yy] ]]
    fi
}
```

--------------------------------

### Full Project Workflow Example

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/acfs/onboard/lessons/20_newproj.md

Demonstrates the typical workflow starting with project creation, spawning agents, and attaching to the project. This sequence ensures the project is prepared before agents begin their work.

```bash
acfs newproj myapp -i
ntm spawn myapp --cc=2
ntm attach myapp
```

--------------------------------

### Install Dependencies and Run Development Server

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/apps/web/README.md

Use these commands to install project dependencies and start the local development server for a Next.js application. Open http://localhost:3000 in your browser to view the running application.

```bash
bun install
bun run dev
```

--------------------------------

### Example Module Installation in Manifest

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/planning/PLAN_TO_CREATE_ACFS.md

Shows how to define installation and verification steps for a module, specifically MCP Agent Mail, within the ACFS manifest.

```yaml
- id: stack.mcp_agent_mail
  description: Like gmail for coding agents
  install:
    - |
      curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh?$(date +%s)" | bash -s -- --yes
  verify:
    - command -v am
    - curl -fsS http://127.0.0.1:8765/health || true

```

--------------------------------

### Generated Script Structure Example

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/README.md

Illustrates the standard structure of a generated bash installation script, including environment checks, installation phases, and verification steps.

```bash
#!/usr/bin/env bash
# AUTO-GENERATED FROM acfs.manifest.yaml - DO NOT EDIT

install_module_id() {
    acfs_require_contract "module.id"  # Validate environment

    if run_installed_check "module.id"; then
        log_step "module.id already installed"
        return 0
    fi

    set_phase "Installing module..."
    run_as_target_shell <<'HEREDOC'
        # Installation commands from manifest
    HEREDOC

    verify_module "module.id"  # Post-install checks
}
```

--------------------------------

### Module Default Installation Metadata

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/README.md

Example of an associative array indicating whether a module is installed by default.

```bash
# Default inclusion in install
declare -gA ACFS_MODULE_DEFAULT
ACFS_MODULE_DEFAULT["lang.bun"]="1"
ACFS_MODULE_DEFAULT["db.postgres18"]="1"
```

--------------------------------

### Add Install Arguments to Module

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/audits/manifest-gap-analysis.md

Example of specifying install arguments for a specific module, such as '--easy-mode' for the UBS module.

```yaml
- id: stack.ubs
  install_args: ["--easy-mode"]
```

--------------------------------

### Main installation script

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/planning/PLAN_TO_HAVE_SINGLE_SOURCE_OF_TRUTH_MANIFEST.md

The main entry point for the installation process, orchestrating various installation phases and sourcing generated scripts.

```bash
#!/usr/bin/env bash
main() {
    parse_args "$@"
    detect_environment
    # Now that runtime vars exist, source generated installers + manifest index.
    source "$ACFS_GENERATED_DIR/manifest_index.sh"
    source "$ACFS_GENERATED_DIR/install_base.sh"
    source "$ACFS_GENERATED_DIR/install_shell.sh"
    source "$ACFS_GENERATED_DIR/install_cli.sh"
    source "$ACFS_GENERATED_DIR/install_lang.sh"
    source "$ACFS_GENERATED_DIR/install_agents.sh"
    source "$ACFS_GENERATED_DIR/install_cloud.sh"
    source "$ACFS_GENERATED_DIR/install_stack.sh"
    source "$ACFS_GENERATED_DIR/install_acfs.sh"

    # Compute effective selection once (deps + filters).
    acfs_resolve_selection

    # Phase 1: Base dependencies
    log_step "1/10" "Checking base dependencies..."
    install_base_system  # FROM GENERATED

    # Phase 2: User normalization (complex orchestration, stays here)
    log_step "2/10" "Normalizing user account..."
    normalize_user  # Hand-maintained (too complex for manifest)

    # Phase 3: Filesystem setup
    log_step "3/10" "Setting up filesystem..."
    install_base_filesystem  # FROM GENERATED

    # Phase 4: Shell setup
    log_step "4/10" "Setting up shell..."
    install_shell  # FROM GENERATED (shell.zsh, cli.modern)

    # Phase 5: CLI tools
    log_step "5/10" "Installing CLI tools..."
    install_cli  # FROM GENERATED

    # Phase 6: Language runtimes
    log_step "6/10" "Installing language runtimes..."
    install_lang  # FROM GENERATED (bun, uv, rust, go, atuin, zoxide)

    # Phase 7: Coding agents
    log_step "7/10" "Installing coding agents..."
    install_agents  # FROM GENERATED (claude, codex, gemini)

    # Phase 8: Cloud & database tools
    log_step "8/10" "Installing cloud & database tools..."
    install_cloud  # FROM GENERATED (vault, postgres, wrangler, supabase, vercel)

    # Phase 9: Dicklesworthstone stack
    log_step "9/10" "Installing Dicklesworthstone stack..."
    install_stack  # FROM GENERATED (ntm, mcp_agent_mail, ubs, bv, cass, cm, caam, slb)

    # Phase 10: Finalization
    log_step "10/10" "Finalizing installation..."
    install_acfs  # FROM GENERATED (onboard, doctor)
    finalize      # Hand-maintained (tmux config, smoke test)
}
```
    }, 
    { 
      
```

```bash
#!/usr/bin/env bash
# Install helpers - module filtering and command execution helpers

# Module filtering arrays (set by parse_args)
ONLY_MODULES=()
ONLY_PHASES=()
SKIP_MODULES=()
NO_DEPS="false"
PRINT_PLAN="false"

# Run a shell string as the target user (supports pipes/heredocs)
run_as_target_shell() {
    local cmd="${1:-""}"
    if [[ -n "$cmd" ]]; then
        # NOTE: Only safe for simple one-liners; generator should prefer heredocs for multi-line scripts.
        run_as_target bash -lc "set -euo pipefail; $cmd"
        return $?
    fi

    # stdin mode (for heredocs):
    # Prepend strict-mode settings inside the script we execute so pipes inside the script are covered.
    run_as_target bash -lc 'set -euo pipefail; (printf "%s\n" "set -euo pipefail"; cat) | bash -s'
}

# Run a shell string as root (install.sh usually ensures we're root already)
run_as_root_shell() {
    local cmd="${1:-""}"
    if [[ -n "$cmd" ]]; then
        if [[ "$EUID" -eq 0 ]]; then
            bash -lc "set -euo pipefail; $cmd"
        else
            $SUDO bash -lc "set -euo pipefail; $cmd"
        fi
        return $?
    fi

    if [[ "$EUID" -eq 0 ]]; then
        bash -lc 'set -euo pipefail; (printf "%s\n" "set -euo pipefail"; cat) | bash -s'
    else
        $SUDO bash -lc 'set -euo pipefail; (printf "%s\n" "set -euo pipefail"; cat) | bash -s'
    fi
}

# Run a shell string as the current user
run_as_current_shell() {
    local cmd="${1:-""}"
    if [[ -n "$cmd" ]]; then
        bash -lc "set -euo pipefail; $cmd"
        return $?
    fi

    bash -lc 'set -euo pipefail; (printf "%s\n" "set -euo pipefail"; cat) | bash -s'
}

# Check if a command exists in the target user's environment
command_exists_as_target() {
    local cmd="$1"
    run_as_target bash -lc "command -v '$cmd' >/dev/null 2>&1"
}

# Effective selection computed once after manifest_index is sourced
declare -A ACFS_EFFECTIVE_RUN=()

acfs_resolve_selection() {
    # Requires scripts/generated/manifest_index.sh to be sourced.
    # Populates ACFS_EFFECTIVE_RUN with the final module set.
    : 
}

should_run_module() {
    local module_id="$1"
    [[ -n "${ACFS_EFFECTIVE_RUN[$module_id]:-}" ]] && return 0
    return 1
}

list_all_modules() {
    # Prefer generated manifest index output; never hardcode.
    acfs_manifest_list_modules
}

```

--------------------------------

### Install Tailscale VPN

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/README.md

Installs Tailscale on the system using the official APT repository. This enables zero-config VPN setup.

```bash
install_tailscale
```

--------------------------------

### Preview Installation Plan

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/reference/MAINTAINER_GUIDE.md

Prints the execution plan for the installation script without actually performing the installation. Useful for debugging and understanding the installation process.

```bash
./install.sh --print-plan
```

--------------------------------

### Bootstrapping a New Project with ACFS

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/methodology/THE_FLYWHEEL_APPROACH_TO_PLANNING_AND_BEADS_CREATION.md

Initializes a new project directory with essential configuration files and version control. Use the --interactive flag for guided setup.

```bash
acfs newproj myproject --interactive
```

--------------------------------

### Example Checksum Configuration

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/acfs/templates/workflows/README.md

Illustrates the format of `checksums.yaml` to determine the installer path. Use `notify-acfs-root.yml` for root install scripts and `notify-acfs-scripts.yml` for scripts in the `scripts/` directory.

```yaml
# Root install.sh → use notify-acfs-root.yml
ntm:
  url: "https://raw.githubusercontent.com/Dicklesworthstone/ntm/main/install.sh"

# scripts/install.sh → use notify-acfs-scripts.yml
mcp_agent_mail:
  url: "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail_rust/refs/heads/main/install.sh"
```

--------------------------------

### Generated Script with DRY_RUN Mode Support

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/planning/PLAN_TO_HAVE_SINGLE_SOURCE_OF_TRUTH_MANIFEST.md

This bash script example illustrates how generated installation scripts handle DRY_RUN mode. It includes checks for existing installations, logs dry-run actions, and conditionally executes the actual installation steps.

```bash
install_lang_bun() {
    local module_id="lang.bun"
    acfs_require_contract "module:${module_id}" || return 1

    # Installed check (runs even in dry-run to show current state)
    if run_as_target_shell "command -v bun >/dev/null 2>&1"; then
        log_detail "$module_id already installed, skipping"
        return 0
    fi

    # DRY_RUN check
    if [[ "${DRY_RUN:-false}" == "true" ]]; then
        log_detail "dry-run: would install $module_id"
        log_detail "dry-run: would run: acfs_run_verified_upstream_script_as_target bun bash"
        return 0
    fi

    log_detail "Installing $module_id"

    # Actual installation
    if ! acfs_run_verified_upstream_script_as_target "bun" "bash"; then
        log_error "$module_id install failed"
        return 1
    fi

    # Verification
    if ! run_as_target_shell "bun --version >/dev/null 2>&1"; then
        log_error "$module_id verification failed"
        return 1
    fi

    log_success "$module_id installed"
}
```

--------------------------------

### Standard Module Example (apt packages)

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/reference/MANIFEST_SCHEMA_VNEXT.md

Defines a standard module for installing CLI tools using apt-get. It includes checks for existing commands and verification steps.

```yaml
- id: cli.modern
  description: Modern CLI tools
  category: cli
  phase: 5
  run_as: root
  optional: false
  enabled_by_default: true
  tags: [recommended, cli-modern]
  dependencies:
    - base.system
  installed_check:
    run_as: current
    command: "command -v rg && command -v fzf"
  install:
    - apt-get install -y ripgrep fzf tmux
  verify:
    - rg --version
    - fzf --version
```

--------------------------------

### Preview Installation Plan

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/README.md

Simulates the ACFS installation process without making any changes, showing exactly what would be installed and in what order. This is helpful for verification before a full install.

```bash
curl -fsSL "..." | bash -s -- --print-plan
```

--------------------------------

### Local QEMU Factory E2E Setup Script

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/README.md

This bash script installs necessary packages for running the factory-host harness locally using QEMU/KVM. It then executes the main test script for the VM environment.

```bash
sudo apt-get install -y qemu-system-x86 qemu-utils cloud-image-utils openssh-client
./tests/vm/test_factory_install_qemu.sh

```

--------------------------------

### Install Command for Agentic Coding Flywheel Setup

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/operations/provider-provisioning-packet.md

This JSON object specifies the installation configuration, including the mode, source reference, and the exact command to execute for setting up the agentic coding flywheel. It is designed for copy-paste fidelity.

```json
{
  "install": {
    "mode": "vibe",
    "sourceRef": "main",
    "command": "curl -fsSL \"https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/install.sh?$(date +%s)\" | bash -s -- --yes --mode vibe",
    "commandRunLocation": "vps-root-shell"
  }
}
```

--------------------------------

### Hetzner Cloud CLI Commands

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/scripts/providers/hetzner.md

Install and use the Hetzner Cloud CLI for managing your servers. Examples include listing servers and initiating an SSH connection.

```bash
# Install
brew install hcloud  # macOS
# or
curl -o hcloud.tar.gz -L https://github.com/hetznercloud/cli/releases/latest/download/hcloud-linux-amd64.tar.gz

# Use
hcloud server list
hcloud server ssh my-server
```

--------------------------------

### Start Onboarding Lesson

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/acfs/onboard/lessons/00_welcome.md

Run this command to start the first lesson of the onboarding tutorial.

```bash
onboard 1
```

--------------------------------

### Install RCH Hook and Start Daemon

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/acfs/onboard/lessons/17_rch.md

Installs the necessary Claude Code hook and starts the local RCH daemon. These are the initial steps to enable remote compilation.

```bash
rch hook install

rch daemon start
```

--------------------------------

### Start and Enable SSH Service

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/acfs/docs/ssh_troubleshooting.md

Start the SSH service on the VPS and configure it to start automatically on boot.

```bash
sudo systemctl start ssh
```

```bash
sudo systemctl enable ssh
```

--------------------------------

### Install Single Module with Dependencies

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/planning/PLAN_TO_HAVE_SINGLE_SOURCE_OF_TRUTH_MANIFEST.md

Installs a specific module and its implicit dependencies. For example, installing `lang.bun` will also include `base.system`.

```bash
./install.sh --only lang.bun
```

--------------------------------

### Quick Install ACFS

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/README.md

Use this command for a quick and automated installation. The installer is idempotent and will resume if interrupted.

```bash
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/install.sh?$(date +%s)" | bash -s -- --yes --mode vibe
```

--------------------------------

### Re-run the onboard tutorial

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/acfs/onboard/lessons/07_flywheel_loop.md

Execute the 'onboard' command to re-run the tutorial and review the setup process.

```bash
onboard

```

--------------------------------

### Install Only Cloud Tools

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/planning/PLAN_TO_HAVE_SINGLE_SOURCE_OF_TRUTH_MANIFEST.md

Installs a specific set of cloud-related modules and their necessary dependencies. For example, installing cloud CLIs might require `base.system` and `lang.bun`.

```bash
./install.sh --only cloud.wrangler,cloud.supabase,cloud.vercel
```

--------------------------------

### Onboard to NTM Tool

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/acfs/onboard/lessons/04_agents_login.md

Proceed to the next step in the setup process by onboarding to the NTM tool, which orchestrates the agents.

```bash
onboard 5
```

--------------------------------

### Navigate to next lesson

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/acfs/onboard/lessons/07_flywheel_loop.md

Proceed to the next lesson in the tutorial by running 'onboard 8'.

```bash
onboard 8

```

--------------------------------

### Full Wizard State Example

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/planning/tui-wizard-design.md

Shows an example of the `WIZARD_STATE` array after the wizard has been completed, containing all collected project configuration details.

```bash
WIZARD_STATE=(
    [project_name]="my-awesome-project"
    [project_dir]="/data/projects/my-awesome-project"
    [tech_stack]="nodejs typescript docker"
    [enable_br]="true"
    [enable_claude]="true"
    [enable_agents]="true"
    [enable_ubsignore]="true"
    [agents_md_content]="# AGENTS.md — my-awesome-project\n\n..."
)
```

--------------------------------

### Check DSR Installation

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/acfs/onboard/lessons/36_dsr.md

Verify that DSR is installed and accessible by checking its help command. This is a basic setup verification step.

```bash
dsr --help
```

--------------------------------

### Get Installation Phase

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/README.md

Retrieves the current installation phase for a specific module. Used for querying module metadata and health checks.

```bash
printf '%s\n' "${ACFS_MODULE_PHASE[stack.ntm]}"  # 9
```

--------------------------------

### Complete Workflow Example

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/acfs/onboard/lessons/07_flywheel_loop.md

A comprehensive workflow demonstrating planning, agent spawning, context setting, prompting, monitoring, scanning, memory updates, and task closing.

```bash
# 1. Plan your work
bv --robot-triage               # Check tasks
br ready --json                 # See what's ready to work on

# 2. Start your agents
ntm spawn myproject --cc=2 --cod=1

# 3. Set context
cm context "Implementing user authentication" --json

# 4. Send initial prompt
ntm send myproject "Let's implement user authentication.
Here's the context: [paste cm output]"

# 5. Monitor and guide
ntm attach myproject            # Watch progress

# 6. Scan before committing
ubs .

# 7. Update memory
cm reflect                      # Distill learnings

# 8. Close the task
br close <task-id>

```

--------------------------------

### Install and Initialize Flywheel Environment

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/methodology/THE_FLYWHEEL_APPROACH_TO_PLANNING_AND_BEADS_CREATION.md

This bash script installs the Flywheel system on a VPS, sets up the environment, and initiates the first project with agents.

```bash
# 1. Rent a VPS (OVH or Contabo, ~$40-56/month, Ubuntu)
# 2. SSH in
ssh ubuntu@your-server-ip

# 3. Run the one-liner
curl -fsSL https://agent-flywheel.com/install.sh | bash

# 4. Reconnect (if was root)
ssh ubuntu@your-server-ip

# 5. Learn the workflow
onboard

# 6. Create your first project
acfs newproj my-first-project --interactive

# 7. Spawn agents
ntm spawn my-first-project --cc=2 --cod=1 --gmi=1

# 8. Start building!
ntm send my-first-project "Let's build something awesome."
```

--------------------------------

### Start Fresh ACFS Installation

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/operations/ubuntu-upgrade.md

Installs ACFS from scratch after performing a clean restart. This command assumes previous state has been backed up or removed.

```bash
# 3. Start fresh
curl -fsSL .../install.sh | bash -s -- --yes --mode vibe
```

--------------------------------

### Sample Agent Mail Start Message

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/methodology/THE_FLYWHEEL_CORE_LOOP.md

An example of an agent mail message indicating the start of a task, including thread ID and subject.

```text
thread_id="br-103"
subject="[br-103] Start: Failed-ingestion admin screen"

Claiming br-103. I am taking the admin failure-review surface and reserving the relevant admin UI files plus the retry handler path. I will send another update once the list view is working and the retry path is wired.
```

--------------------------------

### Example Workflow: Plan Generation and Refinement

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/acfs/onboard/lessons/13_apr.md

A practical example demonstrating the typical workflow: generating an initial plan with Claude Code, refining it using APR, reviewing the output, and then providing the refined plan for implementation.

```bash
# 1. Claude Code generates initial plan
# (creates plan.md)

# 2. Refine with APR
apr refine plan.md -o refined-plan.md

# 3. Review the output
cat refined-plan.md

# 4. Give to Claude Code for implementation
# "Please implement according to refined-plan.md"
```

--------------------------------

### Wrap installation steps with error handling

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/README.md

Executes an installation step, capturing errors without aborting the entire process. Provides context tracking and graceful continuation.

```bash
try_step "Installing ripgrep" install_ripgrep
```

--------------------------------

### List Available Installation Modules

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/reference/MAINTAINER_GUIDE.md

Lists all available modules that can be installed by the installation script. Helps in understanding the scope of available tools and components.

```bash
./install.sh --list-modules
```

--------------------------------

### Initialize ms in a Project Directory

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/acfs/onboard/lessons/11_meta_skill.md

Set up a new project to use meta_skill (ms) by running the 'ms init' command. This creates the necessary '.ms/config.toml' file for project-specific skills.

```bash
ms init
```

--------------------------------

### Install ACFS from a Tagged Release

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/README.md

Installs the Agentic Coding Flywheel Setup from a specific tagged release, recommended for production environments. Ensures stability and reproducibility.

```bash
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/v0.1.0/install.sh" | bash -s -- --yes --mode vibe --ref v0.1.0
```

--------------------------------

### Phased Account Setup Recommendation

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/audits/STEP_BY_STEP_AUDIT_OF_USER_EXPERIENCE.md

Recommends splitting the account setup process into phases to reduce information overload. It prioritizes essential services for immediate setup and suggests others for later.

```markdown
## Phase 1: Essential (do now)
- GitHub (you need this for code backup)
- Anthropic Claude Max (your main AI agent)

## Phase 2: After First Project (do later)
- OpenAI (for Codex CLI)
- Google AI (for Gemini CLI)
```

--------------------------------

### Install ACFS Skipping Ubuntu Upgrade

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/operations/ubuntu-upgrade.md

Installs ACFS while skipping the automatic Ubuntu upgrade process. Useful for initial setup or when managing upgrades separately.

```bash
ts="$(date +%Y%m%d_%H%M%S)"
[ -f /var/lib/acfs/state.json ] && sudo mv /var/lib/acfs/state.json /var/lib/acfs/state.json.backup."$ts"
curl -fsSL .../install.sh | bash -s -- --yes --mode vibe --skip-ubuntu-upgrade
```

--------------------------------

### Support Commands for Quick Start

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/planning/ROOT_AGENTS_MD_PLAN.md

Utility commands for context lookup and running the Ultimate Bug Scanner.

```bash
cm context "<task>" --json
```

```bash
ubs <changed-files>
```

--------------------------------

### Install Script Wizard Mode

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/audits/manifest-gap-analysis.md

This command is used by the website wizard to install the agentic coding flywheel setup with default 'vibe' mode, skipping all prompts.

```bash
curl -fsSL "..." | bash -s -- --yes --mode vibe
```

--------------------------------

### Create Hetzner Server with Cloud-Init

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/scripts/providers/hetzner.md

Use the Hetzner Cloud CLI to create a server and bootstrap it using a cloud-init configuration file. This automates server setup.

```bash
hcloud server create \
  --name acfs-dev \
  --type cpx31 \
  --image ubuntu-24.04 \
  --ssh-key your-key-name \
  --user-data-from-file scripts/providers/hetzner-cloud-init.yml
```

--------------------------------

### Complete tmux Workflow Example

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/acfs/onboard/lessons/03_tmux_basics.md

A practical example demonstrating session creation, pane splitting, navigation, detaching, and reattaching. This sequence helps solidify the core tmux workflow.

```bash
# Create a session
tmux new -s practice

# Split the screen
# Press Ctrl+a, then |

# Move to the new pane
# Press Ctrl+a, then l

# Run something
ls -la

# Detach
# Press Ctrl+a, then d

# Verify it's still running
tmux ls

# Reattach
tmux attach -t practice
```

--------------------------------

### Selection Algorithm Steps

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/planning/PLAN_TO_HAVE_SINGLE_SOURCE_OF_TRUTH_MANIFEST.md

Outlines the sequential steps for initializing the starting set, expanding dependencies, applying skips, validating inputs, and determining the final output for module selection.

```bash
1. INITIALIZE starting_set:
   - If --only provided: starting_set = {explicit module IDs}
   - If --only-phase provided: starting_set = {modules in those phases}
   - Else: starting_set = {modules where enabled_by_default=true}

2. EXPAND dependencies (unless --no-deps):
   - For each module in starting_set:
     - Add all transitive dependencies (from ACFS_MODULE_DEPS)
     - Dependencies are added even if enabled_by_default=false

3. APPLY skips:
   - For each module in --skip:
     - If module is a required dependency of any remaining module:
       - FAIL EARLY: "Cannot skip X: required by Y"
     - Else: Remove from set

4. VALIDATE:
   - If any module ID in --only/--skip is unknown: FAIL EARLY
   - If any phase in --only-phase is invalid (not 1-10): FAIL EARLY

5. OUTPUT:
   - ACFS_EFFECTIVE_RUN[module_id]=1  (hash for O(1) membership test)
   - ACFS_EFFECTIVE_PLAN=(...)        (ordered list, filtered from ACFS_MODULES_IN_ORDER)
```

--------------------------------

### Install ACFS from a Specific Branch

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/README.md

Installs the Agentic Coding Flywheel Setup from a specific branch, suitable for development or testing new features. Allows testing of unreleased changes.

```bash
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/feature/new-tool/install.sh" | bash -s -- --yes --mode vibe --ref feature/new-tool
```

--------------------------------

### Conditional Skip Module Installation

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/reference/MAINTAINER_GUIDE.md

Conditionally adds a module to the SKIP_MODULES array based on the SKIP_NEWTOOL environment variable. This allows skipping specific tool installations during the setup process.

```bash
if [[ "${SKIP_NEWTOOL:-false}" == "true" ]]; then
    SKIP_MODULES+=("category.newtool")
fi
```

--------------------------------

### Check PCR Installation Status

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/acfs/onboard/lessons/38_pcr.md

Verify if the PCR hook is installed and active by checking for its executable and its presence in Claude Code's settings.json. This is a quick way to confirm setup.

```bash
test -x "$HOME/.local/bin/claude-post-compact-reminder"
grep -q "claude-post-compact-reminder" ~/.claude/settings.json \
  || grep -q "claude-post-compact-reminder" ~/.config/claude/settings.json
```

```bash
echo '{"session_id":"demo","source":"compact"}' | ~/.local/bin/claude-post-compact-reminder
```

--------------------------------

### ACFS Manifest Structure Example

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/README.md

Defines tools, their installation commands, and verification logic within the ACFS system. Each module includes a description, category, install commands, and verify commands.

```yaml
version: "1.0"
meta:
  name: "ACFS"
  description: "Agentic Coding Flywheel Setup"
  version: "0.1.0"

modules:
  base.system:
    description: "Base packages + sane defaults"
    category: base
    install:
      - sudo apt-get update -y
      - sudo apt-get install -y curl git ca-certificates unzip tar xz-utils jq build-essential
    verify:
      - curl --version
      - git --version
      - jq --version

  agents.claude:
    description: "Claude Code"
    category: agents
    install:
      - "Install claude code via official method"
    verify:
      - claude --version || claude --help

```

--------------------------------

### Module Description Metadata

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/README.md

Example of an associative array storing human-readable descriptions for installed modules.

```bash
# Module metadata lookup
declare -gA ACFS_MODULE_DESC
ACFS_MODULE_DESC["lang.bun"]="Bun JavaScript/TypeScript runtime"
ACFS_MODULE_DESC["agents.claude"]="Claude Code CLI agent"
```

--------------------------------

### Create New Project Interactively

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/acfs/onboard/lessons/20_newproj.md

Use the interactive mode for a guided TUI wizard to set up your new project. This is recommended for first-time users.

```bash
acfs newproj --interactive
```

```bash
acfs newproj -i
```

--------------------------------

### Install.sh CLI Arguments for Module Selection

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/planning/PLAN_TO_HAVE_SINGLE_SOURCE_OF_TRUTH_MANIFEST.md

Demonstrates various command-line options for the install.sh script to control module installation, including specifying modules, phases, skipping, dry runs, and dependency management.

```bash
# Install only specific module(s)
./install.sh --only lang.bun
./install.sh --only lang.bun,lang.uv,lang.rust

# Install only specific phase(s)
./install.sh --only-phase 6
./install.sh --only-phase 6,7,8

# Skip specific module(s)
./install.sh --skip stack.slb
./install.sh --skip stack.slb,stack.caam

# List available modules
./install.sh --list-modules

# Show what would be installed (combines with --only/--skip)
./install.sh --dry-run --only lang.bun

# Advanced: do NOT auto-run dependency closure (expert-only debugging)
./install.sh --only lang.bun --no-deps

# Print the effective execution plan (after filters + deps)
./install.sh --print-plan --only lang.bun

```

--------------------------------

### Module Dependency Metadata

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/README.md

Example of an associative array defining the dependencies between modules, ensuring correct installation order.

```bash
# Dependency relationships (comma-separated)
declare -gA ACFS_MODULE_DEPS
ACFS_MODULE_DEPS["agents.codex"]="lang.bun"
ACFS_MODULE_DEPS["stack.mcp_agent_mail"]="lang.bun,lang.uv"
```

--------------------------------

### Onboard to Next Lesson

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/acfs/onboard/lessons/01_linux_basics.md

Execute the `onboard` command with the argument `2` to proceed to the next lesson in the series.

```bash
onboard 2
```

--------------------------------

### Define Orchestration Actions

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/audits/manifest-gap-analysis.md

Example of a new manifest section for defining orchestration-only actions, separate from module installations.

```yaml
orchestration:
  - id: finalize.tmux_config
    description: Link tmux configuration
  - id: finalize.state_file
    description: Create installation state tracking
```

--------------------------------

### Get Phase Timings from Summary

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/README.md

Extracts and displays the ID and duration in seconds for each phase from the latest installation summary.

```bash
jq '.phases[] | "\(.id): \(.duration_seconds)s"' ~/.acfs/logs/install_summary_*.json | tail -1
```

--------------------------------

### Print Installation Plan

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/planning/PLAN_TO_HAVE_SINGLE_SOURCE_OF_TRUTH_MANIFEST.md

Use this command to view the installation plan without executing any changes. It's useful for verifying selections and understanding the modules that will be installed.

```bash
./install.sh --print-plan --only lang.bun
```

--------------------------------

### Installer Script Console Output Examples

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/AGENTS.md

Examples of how to use ANSI escape codes for colored output in bash scripts for progress, details, warnings, errors, and success messages. Progress and status messages should be directed to stderr.

```bash
echo -e "\033[34m[1/8] Step description\033[0m"     # Blue progress steps
```

```bash
echo -e "\033[90m    Details...\033[0m"             # Gray indented details
```

```bash
echo -e "\033[33m    Warning message\033[0m"        # Yellow warnings
```

```bash
echo -e "\033[31m    Error message\033[0m"          # Red errors
```

```bash
echo -e "\033[32m    Success message\033[0m"        # Green success
```

--------------------------------

### Run Installer Phase with State Tracking

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/planning/ROADMAP_INSTALLER_RELIABILITY.md

A wrapper function to execute an installation phase, handling checks for prior completion, state updates before and after execution, and error recording.

```bash
# Wrapper for running a phase with state tracking
run_phase() {
    local phase_num=$1
    local phase_name=$2
    local phase_fn=$3

    if is_phase_completed "$phase_num"; then
        log_detail "Phase $phase_num already completed, skipping"
        return 0
    fi

    CURRENT_PHASE=$phase_num
    CURRENT_STEP="Starting $phase_name"
    save_state

    log_step "$phase_num/10" "$phase_name"

    if $phase_fn; then
        complete_phase "$phase_num"
    else
        FAILED_PHASE=$phase_num
        FAILED_STEP="$CURRENT_STEP"
        save_state
        return 1
    fi
}

```

--------------------------------

### br Commands for Quick Start

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/planning/ROOT_AGENTS_MD_PLAN.md

Core commands for the br tool, including checking readiness, updating status, closing issues, and synchronization.

```bash
br ready --json
```

```bash
br update <id> --status in_progress
```

```bash
br close <id> --reason "..."
```

```bash
br sync --flush-only
```

--------------------------------

### Generated Module Function for Installation Check

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/planning/PLAN_TO_HAVE_SINGLE_SOURCE_OF_TRUTH_MANIFEST.md

Example of a generated bash function for a specific module ('lang.bun') that first checks if the module should run based on selection criteria before proceeding with installation steps. It utilizes the `should_run_module` helper function.

```bash
install_lang_bun() {
    local module_id="lang.bun"
    local module_phase="6"
    acfs_require_contract "module:${module_id}" || return 1

    # Check if this module should run
    if ! should_run_module "$module_id" "$module_phase"; then
        log_detail "$module_id skipped (filtered)"
        return 0
    fi

    # ... rest of function
}

```

--------------------------------

### ntm Commands for Quick Start

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/docs/planning/ROOT_AGENTS_MD_PLAN.md

Key commands for ntm to view activity and assign tasks in bulk.

```bash
ntm activity
```

```bash
ntm health <session>
```

```bash
ntm --robot-bulk-assign=<session> --from-bv
```

--------------------------------

### Module Phase Mapping Metadata

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/README.md

Example of an associative array mapping modules to their installation phase, determining the order of execution.

```bash
# Phase mapping (determines install order)
declare -gA ACFS_MODULE_PHASE
ACFS_MODULE_PHASE["base.system"]="1"
ACFS_MODULE_PHASE["lang.bun"]="6"
ACFS_MODULE_PHASE["agents.claude"]="7"
```

--------------------------------

### Iterate Modules in Install Order

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/README.md

Demonstrates how to iterate through modules in their deterministic installation order and filter by category.

```bash
# Iterate modules in deterministic install order
for module in "${ACFS_MODULES_IN_ORDER[@]}"; do
  [[ "${ACFS_MODULE_CATEGORY[$module]}" == "agents" ]] || continue
  printf '%s\n' "$module"
done
```

--------------------------------

### Get Failed Phase from Summary

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/README.md

Retrieves the 'failure' field from the latest installation summary, defaulting to 'No failure' if not present.

```bash
jq '.failure // "No failure"' ~/.acfs/logs/install_summary_*.json | tail -1
```

--------------------------------

### Reload Shell Configuration

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/README.md

If the 'claude' command is not found after installation, try reloading your shell configuration or starting a new shell session.

```bash
source ~/.zshrc
# Or start a new shell
exec zsh
```

--------------------------------

### Module Function Name Mapping

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/README.md

Example of an associative array mapping module identifiers to their corresponding generated installation function names.

```bash
# Generated function name mapping
declare -gA ACFS_MODULE_FUNC
ACFS_MODULE_FUNC["lang.bun"]="install_lang_bun"
```

--------------------------------

### Connect to VPS with Password Login

Source: https://github.com/dicklesworthstone/agentic_coding_flywheel_setup/blob/main/acfs/onboard/lessons/02_ssh_basics.md

Use this command during initial VPS setup to log in as root using a password. This is typically a one-time step before key-based authentication is configured.

```bash
ssh root@YOUR_SERVER_IP
```