scribe

Local single-repo preview and docs maintenance CLI for Scribe. Builds docs/ and CHANGELOG.md from the current checkout, serves the same UI shell as production Scribe, and runs conformance checks for docs-as-code workflows.

Package name: @rambleventures/scribe. Binary: scribe.

Install

In a plugin repo:

npm install --save-dev @rambleventures/scribe

{
  "scripts": {
    "scribe": "scribe"
  }
}

From the ramble-scribe monorepo root, dogfood against this repo's own docs/:

# first time (or after client/UI / CLI changes)
npm run build:scribe

# read-only preview (default)
npm run scribe

# preview with create/edit/delete
npm run scribe:edit

# refresh plugin-style skill stubs (optional dogfood)
npm run scribe:update

That starts the local preview on http://127.0.0.1:4321 with slug scribe (from .scribe.config.yaml). Pass-through args work the same as in plugin repos:

npm run scribe -- doctor
npm run scribe -- --port 4330
npm run scribe -- --edit

To preview a fixture instead of this repo:

npm run scribe -- --cwd packages/scribe-build/test/fixtures --slug publishpress-cart --ref development --no-watch

Commands

| Command | Purpose | |---------|---------| | scribe | Start local preview server (default) | | scribe dev | Same as bare invocation | | scribe doctor [--json] | Docs conformance checks (same engine as CI) | | scribe init | Install skill stubs, scaffold .scribe.config.yaml, docs layout, and sync workflow | | scribe update | Refresh skill stubs and .github/workflows/scribe-sync.yml (after upgrades) |

Run scribe --help, scribe dev --help, scribe doctor --help, scribe init --help, or scribe update --help for details.

Usage

Run from the plugin repo root (the directory that contains docs/):

npm run scribe

The server starts on http://127.0.0.1:4321 by default and redirects / to the first available section landing for the project.

Dev server options

| Flag | Default | Description | |------|---------|-------------| | --slug | .scribe.config.yaml → .tests.config.yaml → package.json / composer.json → folder name | Project slug | | --name | Title-cased slug | Header display name | | --ref | Current git branch (git rev-parse --abbrev-ref HEAD) | Ref label for manifest entries | | --edition | free | free or pro | | --port | 4321 | HTTP port (0 = ephemeral). If busy, tries the next free port | | --host | 127.0.0.1 | Bind host | | --cwd | process.cwd() | Repo root | | --no-watch | watch enabled | Disable rebuild on file changes | | --edit | off (read-only) | Enable create/edit/delete UI and write APIs | | --allow-remote-edits | off | Allow PUT/POST /api/local/* when not bound to loopback (requires --edit) | | -h, --help | | Show help |

Sample URLs

Replace publishpress-cart with your slug:

| URL | Content | |-----|---------| | http://127.0.0.1:4321/dev/publishpress-cart | Dev docs catalog | | http://127.0.0.1:4321/tests/publishpress-cart | Test case catalog | | http://127.0.0.1:4321/public/publishpress-cart/getting-started | Public doc (catalog) | | http://127.0.0.1:4321/public/publishpress-cart/getting-started?view=site | Public site preview (Broadsheet) | | http://127.0.0.1:4321/healthz | Health check |

On the Public Docs tab, use Public site preview in the header to open Broadsheet chrome (?view=site) — the same look as docs.rambleventures.com. Site mode is always read-only; Back to catalog returns to the catalog UI (Edit controls appear only when the server was started with --edit).

Local authoring

By default scribe is read-only preview. Pass --edit (or use npm run scribe:edit in this monorepo) to enable create/edit/delete. With --edit, the UI exposes Edit / Delete on detail panes and catalog create actions; saves write .md files under docs/ and trigger a rebuild (same as the file watcher).

| Action | API | |--------|-----| | Read source | GET /api/local/source?sourcePath=… | | Save | PUT /api/local/source | | New folder (+ README.md) | POST /api/local/folder | | New dev/public doc | POST /api/local/doc | | New test case | POST /api/local/test-case | | New feature | POST /api/local/feature |

When .scribe.config.yaml (or .tests.config.yaml) is present, New feature appends to the config features: map (ADR 0005) instead of writing docs/features/<id>.md. Legacy markdown feature files are used only in repos without a config file.

Modules are engineering tags from module / modules front matter — set them on test cases or docs. There is no docs/modules/ catalog to create.

Security: write endpoints require --edit and a loopback client by default. Binding to 0.0.0.0 without --allow-remote-edits rejects mutations.

Docs maintenance

scribe doctor          # human-readable findings; exit 1 on errors
scribe doctor --json   # ConformanceReport JSON for agents/CI
scribe init            # install skill stubs + config / docs / sync workflow
scribe update          # refresh skill stubs + sync workflow after a package upgrade

Agent skills ship in the package under agent-skills/. scribe init / scribe update install thin stubs under .agents/skills/ that point at those package workflows (including scribe-schemas with test-case and feature schema references). Stub text comes from templates/skill-stub.md. Both commands also write .github/workflows/scribe-sync.yml from templates/scribe-sync.yml (OIDC sync to Scribe). doctor warns when installed stubs lag the package version. Plugin teams: what each skill does and how to replicate — docs/dev/plugin-documentation/agent-skills.md.

How it works

1. scribe-build ingests the local docs/ tree and repo-root CHANGELOG.md.
2. Fragments and manifest are stored in an in-memory KV/R2 shim.
3. A Node HTTP server reuses scribe-app page handlers and the Testlab shell.
4. chokidar watches docs/ and CHANGELOG.md and rebuilds on change.
5. Local write APIs update files on disk, then await the same rebuild path.

Local authoring does not sync to R2/KV or call the build service. Online Scribe remains read-only.

Development

cd packages/scribe-local
npm install
npm test
npm run build

Publish @rambleventures/scribe

From the monorepo root (requires npm publish rights on the scope):

npm run publish:scribe

That runs npm publish --workspace=@rambleventures/scribe --access public. prepublishOnly runs tests; prepack builds dist/ (including dist/agent-skills/ and dist/templates/). After publish, plugin repos should npm install --save-dev @rambleventures/scribe@latest and run npm run scribe -- update.

Architecture: ../../docs/dev/architecture/scribe.md and ../scribe-app/README.md.