### Install Sample Project

Source: https://github.com/dicklesworthstone/automated_plan_reviser_pro/blob/main/tests/fixtures/documents/sample_readme.md

Install the sample project using npm. Ensure you have Node.js and npm installed.

```bash
npm install sample-project
```

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

### Install and Start Oracle Serve Mode

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

Install the Oracle CLI globally and start the serve mode on your local machine. Keep this terminal open to maintain the connection. Ensure you use port 9333.

```bash
# Install Oracle if needed
npm install -g @steipete/oracle

# Start the server (keep this terminal open)
oracle serve --port 9333 --token "your-secret-token"
```

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

### Manual APR Installation

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

Manually install APR by downloading the script and making it executable. Ensure ~/.local/bin is in your PATH. Also installs the required Oracle package.

```bash
# Download script
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/automated_plan_reviser_pro/main/apr -o ~/.local/bin/apr
chmod +x ~/.local/bin/apr

# Ensure ~/.local/bin is in PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc  # or ~/.bashrc
source ~/.zshrc

# Install Oracle (required)
npm install -g @steipete/oracle
```

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

### Install Script

Source: https://github.com/dicklesworthstone/automated_plan_reviser_pro/blob/main/checksums.txt

The installation script for setting up the Automated Plan Reviser Pro.

```bash
eb4626ccca58be2a9278c893618b13655c6f0805b7ee98f6a3127cf5f64a6eba
```

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

### Install APR with cURL

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

Use this one-liner command to install APR. It downloads and executes the installation script.

```bash
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/automated_plan_reviser_pro/main/install.sh" | bash
```

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

### Setup APR Workflow

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

Run the setup wizard to create the necessary `.apr/` directory and configure your workflow if it's missing.

```bash
apr setup  # Run the setup wizard
```

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

### Install Oracle

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

Installs the Oracle package globally using npm. Ensure Node.js is installed first.

```bash
# Oracle
npm install -g @steipete/oracle
```

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

### Agent Workflow Example

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

An example demonstrating the typical agent workflow using the APR CLI.

```APIDOC
## Agent Workflow Example

1.  **Validate**: Run pre-flight validation to catch errors early.
    ```bash
    apr robot validate 5 -w myspec | jq -e '.data.valid' || exit 1
    ```

2.  **Run**: Execute the specified round.
    ```bash
    result=$(apr robot run 5 -w myspec -i)
    ```

3.  **Integrate/Retrieve Output**: Use the `integrate` command or read the output file directly.
    ```bash
    apr integrate 5 -w myspec --copy
    # Output file: .apr/rounds/myspec/round_5.md
    ```

4.  **Check Convergence**: Monitor statistics to determine when to stop iterating.
    ```bash
    apr stats -w myspec  # Aim for Score ≥0.75 for stability
    ```
```

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

### APR CLI: First-time Setup

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

Initiates the interactive setup wizard for the Automated Plan Reviser Pro. This is typically run once when first setting up the tool.

```bash
# First-time setup
apr setup
```

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

### Install jq on Ubuntu/Debian

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

Installs the jq JSON processor on Ubuntu or Debian systems using apt-get.

```bash
# jq (optional, for robot mode)
# Ubuntu/Debian
sudo apt-get install jq
```

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

### Install jq for Robot Mode

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

Install the `jq` utility, which is required for JSON formatting in APR's robot mode. Installation commands vary by operating system.

```bash
# macOS
brew install jq
```

```bash
# Ubuntu/Debian
sudo apt-get install jq
```

```bash
# Fedora
sudo dnf install jq
```

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

### Use Sample Project

Source: https://github.com/dicklesworthstone/automated_plan_reviser_pro/blob/main/tests/fixtures/documents/sample_readme.md

Import and use the sample project's functionality. This requires the project to be installed.

```javascript
const sample = require('sample-project');
sample.doSomething();
```

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

### Install jq on macOS

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

Installs the jq JSON processor on macOS using the Homebrew package manager.

```bash
# jq (optional, for robot mode)
# macOS
brew install jq
```

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

### Install Node.js on Ubuntu/Debian

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

Installs Node.js version 22.x on Ubuntu or Debian systems using curl and apt-get.

```bash
# Node.js (if not installed)
# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
```

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

### Install Oracle CLI

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

Install the Oracle command-line interface globally using npm or use npx for temporary execution. Set APR_NO_NPX=1 to disable the npx fallback.

```bash
# Install Node.js first, then:
npm install -g @steipete/oracle
```

```bash
# Or use npx (works without global install)
npx -y @steipete/oracle --version
```

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

### Install Node.js on macOS

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

Installs Node.js using the Homebrew package manager on macOS.

```bash
# Node.js (if not installed)
# macOS
brew install node
```

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

### Integration Example: Checking Environment and Validation

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

An example of how a coding agent might use robot mode commands to check environment status and perform validation before running a process. It uses `jq` for parsing JSON output.

```bash
# 1. Check environment
status=$(apr robot status)
if ! echo "$status" | jq -e '.data.oracle_available' > /dev/null; then
    echo "Oracle not available"
    exit 1
fi

# 2. Validate before running
validation=$(apr robot validate 5 --workflow fcp-spec)
if ! echo "$validation" | jq -e '.data.valid' > /dev/null; then
    echo "Validation failed:"
    echo "$validation" | jq '.data.errors[]'
    exit 1
fi

```

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

### Example Workflow Configuration

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

A sample YAML configuration file for an APR workflow, defining documents, Oracle model, and round settings.

```yaml
# .apr/workflows/example.yaml

name: example
description: Example workflow for project specification

documents:
  readme: README.md
  spec: SPECIFICATION.md
  implementation: docs/implementation.md  # Optional

oracle:
  model: "5.2 Thinking"

rounds:
  output_dir: .apr/rounds/example
  impl_every_n: 4  # Auto-include implementation every 4th round

template: |
  First, read this README:
  ...

```

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

### Initialize APR Project Setup

Source: https://context7.com/dicklesworthstone/automated_plan_reviser_pro/llms.txt

Initialize APR configuration for a project using an interactive wizard. This command creates the necessary directory structure and a default workflow file.

```bash
# Run interactive setup wizard
apr setup
```

```bash
# Setup creates this directory structure:
# .apr/
# ├── config.yaml          # Global configuration
# ├── workflows/           # Workflow definitions
# │   └── default.yaml     # Default workflow
# └── rounds/              # Round output storage
#     └── default/         # Per-workflow round directories

```

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

### APR Agent Workflow Example

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

An example of the agent workflow, demonstrating the sequence of validation, running, integrating, and checking for convergence. This workflow is designed to iteratively improve protocol specifications.

```bash
# 1. Validate (saves 30+ min on failures)
apr robot validate 5 -w myspec | jq -e '.data.valid' || exit 1

# 2. Run
result=$(apr robot run 5 -w myspec -i)

# 3. After completion, use integrate command or read file directly
apr integrate 5 -w myspec --copy
# File: .apr/rounds/myspec/round_5.md

# 4. Check convergence to know when to stop
apr stats -w myspec  # Score ≥0.75 = approaching stability
```

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

### Install gum on Linux

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

Installs the gum terminal UI tool on Linux systems using curl, gpg, and apt-get. Requires root privileges.

```bash
# gum (optional, for beautiful UI)
# Linux
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list
sudo apt update && sudo apt install gum
```

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

### Terminal Output Examples

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

These examples showcase the rich terminal output generated by APR using gum for enhanced user experience. The output adapts based on the environment and gum's availability.

```shell
╔════════════════════════════════════════════════════════════╗
║    Automated Plan Reviser Pro v1.2.0                       ║
║    Iterative AI-Powered Spec Refinement                    ║
╚════════════════════════════════════════════════════════════╝

╭────────────────────────────────────────────────────────────╮
│  REVISION ROUND 5                                          │
│                                                            │
│  Workflow:     fcp-spec                                    │
│  Model:        5.2 Thinking                                │
│  Include impl: true                                        │
│  Output:       .apr/rounds/fcp-spec/round_5.md             │
╰────────────────────────────────────────────────────────────╯

✓ Oracle running in background (PID: 12345)

╭────────────────────────────────────────────────────────────╮
│  MONITORING COMMANDS                                       │
├────────────────────────────────────────────────────────────┤
│  Check status:      apr status                             │
│  Attach to session: apr attach apr-fcp-spec-round-5        │
╰────────────────────────────────────────────────────────────╯
```

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

### Install apr

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

Installs the Automated Plan Reviser Pro tool. Works on Linux and macOS, auto-installing to ~/.local/bin with PATH detection.

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

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

### Setup apr Workflow

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

Sets up the Automated Plan Reviser Pro workflow interactively, allowing selection of README, specification, and implementation files.

```bash
apr setup
```

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

### APR Setup Command

Source: https://context7.com/dicklesworthstone/automated_plan_reviser_pro/llms.txt

Initializes APR configuration for a project via an interactive wizard, creating workflow files and directory structure. This command is typically run once per project to set up the initial configuration.

```APIDOC
## apr setup

### Description
Initialize APR configuration for a project through an interactive wizard that creates workflow files and directory structure.

The setup wizard guides users through creating their first workflow configuration, prompting for document paths, output directories, and template preferences. It creates the `.apr/` directory structure, generates a default workflow YAML file, and validates that specified documents exist. This command is typically run once when first configuring APR for a new project.

### Method
CLI Command

### Endpoint
N/A (CLI Tool)

### Parameters
None

### Request Example
```bash
# Run interactive setup wizard
apr setup
```

### Response
#### Success Response
- Creates the `.apr/` directory with `config.yaml`, `workflows/`, and `rounds/` subdirectories.
- Generates a default workflow file (e.g., `.apr/workflows/default.yaml`).

#### Response Example
```
# apr setup creates this directory structure:
.apr/
├── config.yaml          # Global configuration
├── workflows/           # Workflow definitions
│   └── default.yaml     # Default workflow
└── rounds/              # Round output storage
    └── default/         # Per-workflow round directories
```
```

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

### Install gum on macOS

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

Installs the gum terminal UI tool on macOS using the Homebrew package manager.

```bash
# gum (optional, for beautiful UI)
# macOS
brew install gum
```

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

### Get cass robot documentation

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

Display documentation for cass in robot-readable format, useful for scripting and automation.

```bash
cass robot-docs guide
```

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

### apr Robot Status TOON Output Example

Source: https://github.com/dicklesworthstone/automated_plan_reviser_pro/blob/main/RESEARCH_FINDINGS.md

Example of the TOON output for the 'robot status' command. This format is more concise than JSON and is suitable for token-sensitive applications.

```yaml
ok: true
code: ok
data:
  configured: false
  default_workflow: ""
  workflow_count: 0
  workflows[0]:
  oracle_available: true
  oracle_method: global
  config_dir: .apr
  apr_home: /home/ubuntu/.local/share/apr
hint: "Run 'apr robot init' to initialize, then 'apr setup' to create workflow"
meta:
  v: 1.2.2
  ts: "2026-01-25T05:51:30Z"
```

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

### APR CLI Basic Usage

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

The fundamental structure for invoking the apr command-line tool. Use this as a starting point for all operations.

```bash
apr [command] [options]
```

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

### apr Robot Status JSON Output Example

Source: https://github.com/dicklesworthstone/automated_plan_reviser_pro/blob/main/RESEARCH_FINDINGS.md

Example of the JSON output for the 'robot status' command. It includes status flags, configuration details, and system information.

```json
{
  "ok": true,
  "code": "ok",
  "data": {
    "configured": false,
    "default_workflow": "",
    "workflow_count": 0,
    "workflows": [],
    "oracle_available": true,
    "oracle_method": "global",
    "config_dir": ".apr",
    "apr_home": "/home/ubuntu/.local/share/apr"
  },
  "hint": "Run 'apr robot init' to initialize, then 'apr setup' to create workflow",
  "meta": {
    "v": "1.2.2",
    "ts": "2026-01-25T05:50:52Z"
  }
}
```

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

### APR CLI: Run Revision Round with Login and Wait

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

Executes the first revision round, requiring a login and waiting for completion. Use '--login' for initial setup and '--wait' for synchronous execution.

```bash
# Run revision round 1 (first time requires --login)
apr run 1 --login --wait
```

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

### Start bv Triage

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

Initiate the bv graph-aware triage engine with the robot triage command. This is the primary entry point for analysis.

```bash
bv --robot-triage        # THE MEGA-COMMAND: start here
```

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

### bv Robot Plan Command

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

Use the `--robot-plan` command with bv to get parallel execution tracks and unblocks lists.

```bash
--robot-plan
```

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

### Get bv Next Recommendation

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

Obtain the single top recommendation and claim command from the bv triage engine with minimal output.

```bash
bv --robot-next          # Minimal: just the single top pick + claim command
```

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

### Set TOON Output Format

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

Use the `--format toon` flag to enable TOON output when `toon_rust` is installed. Format precedence is `--format` > `APR_OUTPUT_FORMAT` > `TOON_DEFAULT_FORMAT` > `json`.

```bash
apr robot status --format toon
```

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

### Get cass capabilities

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

Retrieve the capabilities of the cass system in JSON format. Useful for understanding available features and options.

```bash
cass capabilities --json
```

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

### Project Directory Structure

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

Illustrates the top-level directory structure of the APR project, including main scripts, configuration files, and example workflows.

```tree
automated_plan_reviser_pro/
├── apr                  # Main script (~800 LOC)
├── install.sh           # Curl-bash installer
├── README.md            # Comprehensive documentation
├── AGENTS.md            # This file
├── VERSION              # Semver version file
├── LICENSE              # MIT License
├── workflows/           # Example workflow configs
│   └── fcp-example.yaml
├── templates/           # Prompt templates
│   └── standard.md
└── lib/                 # Shared functions (future)
```

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

### Get bv Plan Summary with jq

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

Use jq to parse the JSON output of `bv --robot-plan` and extract the summary of the highest impact unblock target.

```bash
bv --robot-plan | jq '.plan.summary.highest_impact'
```

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

### Get Top Recommendation from bv with jq

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

Use jq to parse the JSON output of `bv --robot-triage` and extract the first recommendation.

```bash
bv --robot-triage | jq '.recommendations[0]'
```

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

### Example JSON Export Structure

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

This JSON structure represents the full metrics data, including schema version, workflow details, round-by-round statistics, and convergence detection results.

```json
{
  "schema_version": "1.0.0",
  "workflow": "my-project",
  "rounds": [
    {
      "round": 1,
      "timestamp": "2026-01-10T14:30:00Z",
      "output": {
        "char_count": 15200,
        "word_count": 2500,
        "line_count": 320
      }
    }
  ],
  "convergence": {
    "detected": false,
    "confidence": 0.78,
    "signals": {
      "output_trend": 0.85,
      "change_velocity": 0.75,
      "similarity_trend": 0.72
    }
  }
}
```

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

### Run UBS with Language Filter

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

Execute the Ultimate Bug Scanner (UBS) with a language filter to speed up analysis. This example filters for bash and shell scripts.

```bash
ubs --only=bash,shell scripts/
```

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

### APR CLI: Attach to Running Session

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

Connects to a previously started or completed revision session. Provide the session identifier to attach.

```bash
# Attach to a running session
apr attach apr-default-round-3
```

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

### Launch Interactive Dashboard

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

Opens a full-screen interactive dashboard for real-time convergence gauge visualization and round-by-round trend analysis.

```bash
apr dashboard
```

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

### Basic br Commands for Issue Tracking

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

These commands demonstrate the fundamental usage of the 'br' tool for managing issues, including checking ready work, creating new issues, updating their status, and closing them.

```bash
br ready --json                    # Check ready work
br create "Issue title" -t task    # Create issue
br update br-42 --status in_progress  # Update status
br close br-42 --reason "Done"     # Complete issue
```

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

### APR Robot Help Command

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

Returns complete API documentation in JSON format, useful for coding agents to discover capabilities.

```bash
apr robot help
```

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

### APR Robot Init

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

Initializes the `.apr/` directory structure. This command is idempotent and can be safely called multiple times.

```APIDOC
## POST /robot/init

### Description
Initializes the `.apr/` directory structure. It is idempotent and safe to call multiple times.

### Method
POST

### Endpoint
`/robot/init`

### Request Example
```bash
apr robot init
```

### Response
#### Success Response (200)
- **created** (boolean) - Indicates if the directory structure was created.
- **existed** (boolean) - Indicates if the directory structure already existed.

#### Response Example
```json
{
  "ok": true,
  "code": "ok",
  "data": {
    "created": true,
    "existed": false
  }
}
```
```

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

### GET /status

Source: https://github.com/dicklesworthstone/automated_plan_reviser_pro/blob/main/tests/fixtures/documents/sample_spec.md

Endpoint to check the health status of the service.

```APIDOC
## GET /status

### Description
Provides a health check for the service.

### Method
GET

### Endpoint
/status

### Response
#### Success Response (200)
- **status** (string) - Indicates the health status of the service (e.g., "OK").

#### Response Example
```json
{
  "status": "OK"
}
```
```

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

### GET /result/:id

Source: https://github.com/dicklesworthstone/automated_plan_reviser_pro/blob/main/tests/fixtures/documents/sample_spec.md

Endpoint to retrieve the result of a processing job.

```APIDOC
## GET /result/:id

### Description
Retrieves the result associated with a specific processing job ID.

### Method
GET

### Endpoint
/result/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the processing job.

### Response
#### Success Response (200)
- **status** (string) - The status of the processing job (e.g., "completed", "processing", "failed").
- **result** (string) - The result of the processing job, if completed.

#### Response Example
```json
{
  "status": "completed",
  "result": "processed output data"
}
```
```

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

### Run UBS on Whole Project

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

Run the Ultimate Bug Scanner (UBS) on the entire project directory. This provides a comprehensive check but takes longer.

```bash
ubs .                                   # Whole project
```

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

### List apr Workflows

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

Lists all configured apr workflows.

```bash
apr list
```

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

### APR Robot Init Command

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

Initializes the `.apr/` directory structure. This command is idempotent and safe to run multiple times.

```bash
apr robot init
```

```json
{
  "ok": true,
  "code": "ok",
  "data": {
    "created": true,
    "existed": false
  }
}
```

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

### Show full issue details with dependencies using Beads

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

Display the complete details of a specific issue, including its dependencies, using the Beads issue tracker.

```bash
br show <id>          # Full issue details with dependencies
```

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

### List APR Workflows

Source: https://context7.com/dicklesworthstone/automated_plan_reviser_pro/llms.txt

List all configured workflows and their basic information. Use '--verbose' for more detailed information. This command helps manage available workflows.

```bash
# List all workflows
apr list
```

```bash
# List with detailed information
apr list --verbose
```

```bash
# Example output:
# Workflows:
#   default     - Default specification review (3 docs)
#   fcp-spec    - Flywheel Connector Protocol (4 docs)

```

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

### Quality Gate Checks for APR and install.sh

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

These commands are used to perform quality gate checks on the 'apr' script and 'install.sh'. They include running ShellCheck for script analysis and bash syntax checks.

```bash
# ShellCheck
shellcheck apr install.sh

# Syntax check
bash -n apr
bash -n install.sh
```

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

### apr Architecture Overview

Source: https://github.com/dicklesworthstone/automated_plan_reviser_pro/blob/main/RESEARCH_FINDINGS.md

Illustrates the high-level architecture of the apr tool, showing the flow from JSON response generation to TOON encoding via the 'toon.sh' script.

```text
apr (bash)
  └── robot_json() builds JSON response
      └── robot_json_to_toon() loads toon.sh
          └── toon_encode pipes through tru
              └── TOON output to stdout
```

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

### Run UBS on Specific Files

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

Execute the Ultimate Bug Scanner (UBS) on specific files, such as install.sh. This is a fast check before committing.

```bash
ubs apr install.sh                      # Specific files (< 1s) — USE THIS
```

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

### APR CLI: Run Revision Round in Background

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

Starts a revision round and allows the process to run in the background. Omit '--wait' for asynchronous execution.

```bash
# Run round 2 in background
apr run 2
```

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

### APR Robot Help

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

Provides complete API documentation in JSON format, useful for coding agents.

```APIDOC
## GET /robot/help

### Description
Returns complete API documentation in JSON format, useful for coding agents to discover capabilities.

### Method
GET

### Endpoint
`/robot/help`

### Request Example
```bash
apr robot help
```

### Response
#### Success Response (200)
- The response contains the full API documentation in JSON format, mirroring the structure of this document.
```

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

### APR CLI: Render and Copy for Manual Paste

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

Renders the output for manual pasting and copies it to the clipboard. Use '--render' and '--copy' flags together for this workflow.

```bash
# Render for manual paste into ChatGPT
apr run 4 --render --copy
```

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

### Configure Round Implementation Frequency in APR Workflow

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

Set the frequency for including implementation details in review rounds. This example ensures implementation is included every 4th round.

```yaml
rounds:
  output_dir: .apr/rounds/fcp
  impl_every_n: 4  # Include implementation every 4th round (4, 8, 12, ...)
```

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

### GPT Pro Prompt for Plan Revision

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

A markdown-formatted prompt for GPT Pro, instructing it to review a README and a specification document, and provide detailed revisions with git-diff style changes.

```markdown
First, read this README:

```
<paste contents of readme file>
```

---

NOW: Carefully review this entire plan for me and come up with your best
revisions in terms of better architecture, new features, changed features,
etc. to make it better, more robust/reliable, more performant, more
compelling/useful, etc.

For each proposed change, give me your detailed analysis and
rationale/justification for why it would make the project better along
with the git-diff style change versus the original plan shown below:

```
<paste contents of spec document>
```
```

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

### Example CSV Export Data

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

This CSV format provides tabular data for metrics, including round number, timestamp, output statistics, similarity score, and convergence score, suitable for spreadsheet analysis.

```csv
"round","timestamp","output_chars","output_words","output_lines","similarity","convergence_score"
1,"2026-01-10T14:30:00Z",15200,2500,320,"",0.0
2,"2026-01-10T16:45:00Z",14100,2350,298,0.72,0.45
3,"2026-01-11T09:15:00Z",12800,2150,275,0.81,0.68
```

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

### Per-Project Configuration Structure

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

Shows the directory structure created by APR within a project for configuration and round outputs.

```tree
<project>/
└── .apr/
    ├── config.yaml           # Default workflow setting
    ├── workflows/            # Workflow definitions
    │   └── <name>.yaml
    ├── rounds/               # GPT Pro outputs
    │   └── <workflow>/
    │       └── round_N.md
    └── templates/            # Custom prompt templates
```

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

### Run APR with Explicit Pre-Flight Validation

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

Use this command to run APR with pre-flight checks enabled. Pre-flight validation ensures all preconditions are met before starting an operation, catching potential issues early.

```bash
# Run with explicit pre-flight (default behavior)
apr run 5
```

```bash
# Skip pre-flight for faster startup
apr run 5 --no-preflight
```

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

### APR Round Including Implementation Docs

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

Run an APR round and explicitly include implementation documentation. This is useful for periodic checks.

```bash
apr run 3 --include-impl
```

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

### APR Dependencies

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

Lists the required and optional dependencies for APR, including shell, node.js, and specific tools like `jq` and `gum` for enhanced functionality.

```text
Required: bash 4+, node 18+, oracle (or npx @steipete/oracle)
Optional: gum (TUI), jq (robot mode), delta (prettier diffs)
```

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

### First APR Round with Manual Login

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

Initiate the first round of APR with manual login enabled and wait for completion. This is typically required the first time you run APR.

```bash
apr run 1 --login --wait
```

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

### POST /process

Source: https://github.com/dicklesworthstone/automated_plan_reviser_pro/blob/main/tests/fixtures/documents/sample_spec.md

Endpoint to initiate data processing.

```APIDOC
## POST /process

### Description
Initiates the processing of provided data.

### Method
POST

### Endpoint
/process

### Request Body
- **data** (string) - Required - The data to be processed.

### Request Example
```json
{
  "data": "sample input data"
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the processing has started.
- **job_id** (string) - The unique identifier for the processing job.

#### Response Example
```json
{
  "message": "Processing started successfully.",
  "job_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}
```
```

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

### Run Workflow and Capture Result

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

Execute a workflow (e.g., 'myspec' with 5 rounds) and include implementation details using `-i`. The output, including the result slug, PID, and file paths, is captured in the `result` variable.

```bash
result=$(apr robot run 5 -w myspec -i)
```

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

### Launch APR Interactive Dashboard

Source: https://context7.com/dicklesworthstone/automated_plan_reviser_pro/llms.txt

Launches a real-time TUI interface for monitoring multiple workflows, their status, active sessions, and key metrics. Supports keyboard navigation and custom refresh intervals.

```bash
# Launch interactive dashboard
apr dashboard
```

```bash
# Dashboard with specific refresh interval
apr dashboard --refresh 5
```

```bash
# Dashboard for specific workflows only
apr dashboard -w fcp-spec,api-design
```

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

### APR Robot Workflows Command

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

Lists all configured workflows along with their descriptions. This is useful for understanding available automation tasks.

```bash
apr robot workflows
```

```json
{
  "ok": true,
  "code": "ok",
  "data": {
    "workflows": [
      {"name": "fcp-spec", "description": "Flywheel Connector Protocol specification"},
      {"name": "auth-protocol", "description": "Authentication protocol design"}
    ]
  }
}
```

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

### Analyze bv Cycles with jq

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

Use jq to parse the JSON output of `bv --robot-insights` and extract information about circular dependencies.

```bash
bv --robot-insights | jq '.Cycles'
```

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

### Run All APR Tests

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

Execute the entire test suite for APR. This command initiates all available tests, including unit and end-to-end scenarios.

```bash
./tests/run_tests.sh
```

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

### APR CLI: Run Revision Round with Implementation Doc

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

Includes the implementation document when running a revision round. Use the '--include-impl' flag for this purpose.

```bash
# Run round 3 with implementation doc
apr run 3 --include-impl
```

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

### APR Options

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

A list of available command-line options for APR, including workflow selection (`-w`), output control (`-o`, `--compact`, `--json`), and execution modifiers (`--dry-run`, `--wait`, `--no-preflight`).

```text
-w, --workflow NAME   Workflow (default: from config)
```

```text
-i, --include-impl    Include implementation doc
```

```text
-d, --dry-run         Preview oracle command
```

```text
-c, --copy            Copy to clipboard
```

```text
-o, --output FILE     Output to file
```

```text
-v, --verbose         Debug output
```

```text
--wait                Block until completion
```

```text
--login               Browser login (first time)
```

```text
--no-preflight        Skip validation
```

```text
--hours NUM           Status window (default: 72)
```

```text
--compact             Minified JSON (robot mode)
```

```text
--json                JSON output for stats command
```

```text
--detailed            Detailed metrics for stats command
```

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

### Copy APR Claude Code Integration Prompt to Clipboard

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

Generate and directly copy an optimized prompt for handing APR feedback to Claude Code for integration to the system clipboard.

```bash
apr integrate 5 --copy
```

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

### Integrate and Output Prompt

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

Integrates changes and outputs the generated prompt to a file for later use. Use the `-c` flag for direct pasting into Claude Code.

```bash
apr integrate 5 --output round5_prompt.md
```

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

### Show issues ready to work with Beads

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

Display issues that are ready to be worked on, meaning they have no outstanding blockers, using the Beads workflow integration.

```bash
# CLI commands for agents
br ready              # Show issues ready to work (no blockers)
```

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

### Run APR with Remote Connection

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

Once the remote connection is successfully configured and tested, you can run APR commands as usual. The commands will be executed through the remote browser session.

```bash
apr run 1  # Works over the remote connection
```

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

### Common Options

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

A list of commonly used options for APR commands.

```APIDOC
## Common Options

- `-w, --workflow NAME`: Specify the workflow name (defaults to configuration).
- `-i, --include-impl`: Include implementation details in the output.
- `-d, --dry-run`: Preview the Oracle command without execution.
- `-c, --copy`: Copy the output to the clipboard.
- `-o, --output FILE`: Redirect output to a specified file.
- `-v, --verbose`: Enable debug output.
- `--wait`: Block execution until the process completes.
- `--login`: Initiate browser login (for first-time use).
- `--no-preflight`: Skip the pre-flight validation step.
- `--hours NUM`: Set the status window duration in hours (default: 72).
- `--compact`: Output in a minified JSON format (robot mode).
- `--json`: Enable JSON output for the `stats` command.
- `--detailed`: Request detailed metrics for the `stats` command.
```

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

### Oracle CLI Session Attach with Render

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

Attach to a specific Oracle session and render its output, typically used for APR reviews.

```bash
npx -y @steipete/oracle session apr-fcp-spec-round-5 --render
```

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

### List all open issues with Beads

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

Retrieve a list of all currently open issues within the Beads issue tracking system.

```bash
br list --status=open # All open issues
```

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

### APR Robot Workflows

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

Lists all configured workflows along with their descriptions.

```APIDOC
## GET /robot/workflows

### Description
Lists all configured workflows with their descriptions.

### Method
GET

### Endpoint
`/robot/workflows`

### Request Example
```bash
apr robot workflows
```

### Response
#### Success Response (200)
- **workflows** (array of objects) - A list of workflows, each with:
  - **name** (string) - The name of the workflow.
  - **description** (string) - A description of the workflow.

#### Response Example
```json
{
  "ok": true,
  "code": "ok",
  "data": {
    "workflows": [
      {"name": "fcp-spec", "description": "Flywheel Connector Protocol specification"},
      {"name": "auth-protocol", "description": "Authentication protocol design"}
    ]
  }
}
```
```

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

### Sync Beads issues and commit to Git

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

Export current Beads issues to JSONL format and prepare them for commit to Git. This command only flushes data; manual git commands are required afterward.

```bash
br sync --flush-only  # Export to JSONL (then manually: git add .beads/ && git commit)
```

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

### Generate APR Claude Code Integration Prompt

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

Generate an optimized prompt for handing APR feedback to Claude Code for integration.

```bash
apr integrate 5
```

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

### View a specific session in cass

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

View the details of a specific session from a JSONL file in cass. The --json flag ensures the output is in JSON format.

```bash
cass view /path/to/session.jsonl -n 42 --json
```

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

### Render APR Session with Oracle

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

Use Oracle directly to render a specific APR session. This can be helpful for debugging or accessing session data.

```bash
npx -y @steipete/oracle session apr-default-round-5 --render
```

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

### APR List Command

Source: https://context7.com/dicklesworthstone/automated_plan_reviser_pro/llms.txt

Lists all configured workflows and their basic information, allowing for quick overview and management of available workflows.

```APIDOC
## apr list

### Description
List all configured workflows and their basic information for workflow management.

The list command scans the `.apr/workflows/` directory and displays all available workflow configurations with their names, descriptions, and document counts. It provides a quick overview of available workflows and their readiness status (whether required documents exist).

### Method
CLI Command

### Endpoint
N/A (CLI Tool)

### Parameters
#### Query Parameters
- **--verbose** (boolean) - Optional - Display more detailed information about each workflow.

### Request Example
```bash
# List all workflows
apr list

# List with detailed information
apr list --verbose
```

### Response
#### Success Response
- Lists the names, descriptions, and document counts of configured workflows.

#### Response Example
```
# Example output:
Workflows:
  default     - Default specification review (3 docs)
  fcp-spec    - Flywheel Connector Protocol (4 docs)
```

#### Success Response (Verbose)
```
# Example verbose output:
Workflows:
  default:
    description: Default specification review
    document_count: 3
    status: Ready
  fcp-spec:
    description: Flywheel Connector Protocol
    document_count: 4
    status: Ready
```
```

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

### Run UBS on Staged Files

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

Run the Ultimate Bug Scanner (UBS) on all staged files before committing. This ensures code quality before it enters the repository.

```bash
ubs $(git diff --name-only --cached)    # Staged files — before commit
```

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

### Run Robot Workflow

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

Executes a robot workflow with a specified ID and captures the session slug and output file path for later reference. Requires `jq` for JSON parsing.

```bash
result=$(apr robot run 5 --workflow fcp-spec)
slug=$(echo "$result" | jq -r '.data.slug')
output_file=$(echo "$result" | jq -r '.data.output_file')

echo "Started session: $slug"
echo "Output will be at: $output_file"
```

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

### Test Oracle Remote Connection

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

Verify the connection between the remote server and your local Oracle serve instance. This command attempts to interact with ChatGPT via the established remote browser session.

```bash
oracle -p "Say exactly: Connection successful" -e browser -m "5.2 Thinking"
```

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

### Configure Remote Server Environment Variables

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

Set environment variables on the remote server to point to your local machine's Oracle serve instance. For persistent settings, add these to your shell's configuration file (e.g., ~/.zshrc or ~/.bashrc).

```bash
# Set environment variables (add to ~/.zshrc or ~/.bashrc for persistence)
export ORACLE_REMOTE_HOST="192.168.1.100:9333"  # Your local machine's IP
export ORACLE_REMOTE_TOKEN="your-secret-token"  # Must match --token above

# Or for Tailscale (recommended for remote servers)
export ORACLE_REMOTE_HOST="100.x.x.x:9333"      # Tailscale IP of local machine
```

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

### Register Agent for MCP Mail

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

Register an agent for a specific project to enable communication via MCP Mail. Ensure the project key is an absolute path.

```python
ensure_project(project_key=<abs-path>)
register_agent(project_key, program, model)
```

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

### Integrate Workflow Results

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

After a workflow completes, use the `apr integrate` command to process the output. The `--copy` flag copies the result to the clipboard. The output file is typically located at `.apr/rounds/<workflow>/round_N.md`.

```bash
apr integrate 5 -w myspec --copy
```

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

### Manually Update APR with Sudo

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

If APR fails to prompt for sudo during an update in a system directory, manually update the `apr` executable using `curl` and `chmod` with elevated privileges.

```bash
# Check where apr is installed
which apr
```

```bash
# If in /usr/local/bin, update will prompt for sudo
# If that fails, manually update:
sudo curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/automated_plan_reviser_pro/main/apr -o /usr/local/bin/apr
sudo chmod +x /usr/local/bin/apr
```

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

### Backfill apr Metrics

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

Generates metrics from existing apr rounds.

```bash
apr backfill
```

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

### Attach to APR Session

Source: https://context7.com/dicklesworthstone/automated_plan_reviser_pro/llms.txt

Attach to a running Oracle session to monitor AI output in real-time. Use '-w' to specify a workflow and '--wrap' for line wrapping in narrow terminals.

```bash
# Attach to the most recent active session
apr attach
```

```bash
# Attach to a specific workflow's session
apr attach -w fcp-spec
```

```bash
# Attach with line wrapping for narrow terminals
apr attach --wrap
```

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

### Standard Response Format

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

All robot mode commands return a consistent JSON envelope, including status, data, and metadata.

```APIDOC
### Response Format

All robot mode commands return a consistent JSON envelope:

```json
{
  "ok": true,
  "code": "ok",
  "data": { ... },
  "hint": "Optional helpful message for debugging",
  "meta": {
    "v": "1.2.0",
    "ts": "2026-01-12T19:14:00Z"
  }
}
```

On failure, `ok` becomes `false` and `code` contains a stable, semantic failure class. For grep-friendly automation, fatal failures also emit a single-line stderr tag:

`APR_ERROR_CODE=<code>`

| Code | Meaning |
|------|---------|
| `ok` | Success |
| `usage_error` | Bad arguments (missing/invalid round/workflow/option) |
| `not_configured` | No `.apr/` directory / not initialized |
| `config_error` | Workflow/config invalid (missing fields/files, cannot create dirs) |
| `validation_failed` | Preconditions not met (prompt QC, output exists, metrics missing) |
| `dependency_missing` | Required dependency missing (e.g. oracle/jq) |
| `busy` | Single-flight/busy (lock held / cannot proceed without waiting) |
| `network_error` | Network/remote unreachable (when remote mode is used) |
| `update_error` | Self-update failed |
| `not_implemented` | Feature unsupported in this install |
| `internal_error` | Unexpected failure (bug/unknown state) |
```