Uraniborg

Uraniborg is a local-first CLI for deterministic draft improvement loops.

It takes a Markdown research draft, runs an independent review pass, revises the draft against that review, records structured memory about what changed, and repeats for a fixed number of iterations.

Core loop:

draft -> peer review -> refinement -> memory update -> repeat -> final draft

Status

The v1 implementation is complete against the locked OpenSpec change and the canonical specs now live under:

• openspec/specs/environment-setup/spec.md
• openspec/specs/model-selection/spec.md
• openspec/specs/iterative-draft-run/spec.md
• openspec/specs/run-recovery-and-history/spec.md

Automated validation is in place, but live UAT against a real external Feynman runtime and real provider credentials is still required.

What The CLI Supports

The current CLI surface is:

• init
  • configure Uraniborg-owned refinement settings
• doctor
  • validate environment readiness
• models
  • inspect review and refine model availability
• run <file>
  • create and execute a new run
• resume <run-id>
  • resume an interrupted run
• history
  • list prior runs

Project Layout

• src/
  • CLI, orchestration, review, refine, memory, config, and run state code
• tests/
  • automated unit and smoke coverage
• openspec/specs/
  • canonical locked specs
• openspec/changes/archive/2026-04-24-build-uraniborg-v1/
  • archived implementation change record
• notes/uraniborg-v1-uat-plan.md
  • structured UAT plan
• notes/uraniborg-v1-uat-instructions.md
  • step-by-step UAT execution guide

Requirements

• Node.js >= 20
• npm
• a compatible external Feynman installation available as feynman on PATH
• credentials for the Uraniborg-owned refine endpoint you configure during init

Uraniborg does not bundle, provision, or own Feynman. Install or expose Feynman separately before running review-dependent commands.

Install

Install the CLI from npm:

npm install -g uraniborg

Then check the local environment:

uraniborg doctor

If Feynman is missing or incompatible, uraniborg doctor, uraniborg models, and run preflight report prerequisite guidance. Review-model, AlphaXiv, and web-search setup problems remain Feynman readiness issues; they are reported separately from Feynman compatibility.

Local Development

Install dependencies:

npm install

Validate the codebase:

npm run validate

Build the project:

npm run build

Run the built CLI locally:

node dist/cli/main.js --help

Quickstart

1. Install the CLI:

npm install -g uraniborg

2. Check prerequisites:

uraniborg doctor

3. Configure refinement:

uraniborg init

4. Check model availability:

uraniborg models

5. Run a draft:

uraniborg run path/to/draft.md --iterations 1

6. Inspect prior runs:

uraniborg history

7. Resume an interrupted run:

uraniborg resume <run-id>

Source Checkout Quickstart

1. Build the CLI from source:

npm run build

2. Configure refinement:

node dist/cli/main.js init

3. Check readiness:

node dist/cli/main.js doctor
node dist/cli/main.js models

4. Run a draft:

node dist/cli/main.js run path/to/draft.md --iterations 1

5. Inspect prior runs:

node dist/cli/main.js history

6. Resume an interrupted run:

node dist/cli/main.js resume <run-id>

Run Artifacts

Uraniborg stores app state under ~/.uraniborg/.

Each run persists local artifacts including:

• run.json
• config.snapshot.json
• original.md
• current.md
• final.md
• information-highway.md
• iter-N/input.md
• iter-N/review.md
• iter-N/refined.md
• iter-N/changes.md
• per-step logs

UAT

For structured acceptance testing:

• read the plan: notes/uraniborg-v1-uat-plan.md
• follow the execution guide: notes/uraniborg-v1-uat-instructions.md

Packaging

Production builds emit the CLI entrypoint at dist/cli/main.js, matching the npm bin contract. The npm package is allowlist-based and ships only dist/**, package.json, README.md, and LICENSE.