SCRIPTONIA 0.10.3 · CUSTOMER GUIDE

Give your coding agent the context it is missing.

Relay connects customer evidence, prior decisions, and the real codebase. It produces a cited build plan, then helps you check whether the resulting change stayed on product.

Fastest pathSet up one repository

You approve every step

Read https://relayevals.com/agents.md and set up Relay 0.10.3 for this repository. Use the exact committed Git root and stop only after `brain status --check` shows READY, fresh, and coverage PASS.

Paste this into Claude Code, Codex, Cursor, or Hermes from the repository you want to use. You approve browser sign-in and confirm the exact Git root.

Node 22 / 24 / 26Committed Git repositoryClaude, Codex, Cursor, Hermes, or a developerNo provider API keys needed

Contents

START HERE

What Relay does—in one picture.

AI coding agents know code. They usually do not know which customer asked, what your team already decided, or where the safe boundary of this change ends.

01Customer evidenceTickets, calls, notes

02Product memorySources and decisions

03Deep BrainThe real repository

04PLAN.mdScope and proof

05Coding agentImplements the plan

06Verify and learnReview and regression

✓

Repository Deep Brain

A local, versioned map of files, symbols, imports, tests, Git evidence, and relationships.

✓

Product memory

Customer evidence, source references, themes, comments, and hosted planning history.

✓

Executable PLAN.md

A cited contract containing the goal, Non-goals, file operations, acceptance criteria, and tests.

✓

Verification evidence

A readable report and CI gate that check the declared contract without replacing your normal tests.

The honest promise

Relay reduces missing context and makes evidence inspectable. It does not make AI output automatically correct, replace product judgment, or certify production readiness.

FIRST SUCCESSFUL RUN

Set up one repository, step by step.

Run these commands in a terminal. You need a Git repository with at least one commit. Node 24 LTS is recommended; maintained Node 22, 24, and 26 releases are supported.

Downloaded a ZIP with no Git commit?

Create a safe empty baseline first. This does not stage the project files.

terminal

$ git init
$ git commit --allow-empty -m "Initialize repository"

Check your computer

This offline check finds unsupported Node versions, SQLite issues, missing parser assets, Git, and search-tool problems.

terminal

$ npx --yes relayai-cli@latest doctor

Sign in

A browser opens. Login stores your Relay account token locally and installs the Claude Code skill. It does not initialize a repository.

terminal

$ npx --yes relayai-cli@latest login

Enter the exact Git root

Relay binds one exact committed repository root. Run the first command, then enter the path it prints.

terminal

$ git rev-parse --show-toplevel
$ cd /the/exact/path/printed/above

Initialize this repository

This writes the managed AGENTS.md instructions and creates the first credential-free structural brain.

terminal

$ npx --yes relayai-cli@latest init --about "What this product does and who it serves"

Require a healthy brain

Continue only when the active generation says READY, the snapshot is fresh, and coverage is PASS.

terminal

$ npx --yes relayai-cli@latest brain status --check

Add one real customer statement

Use a ticket, note, transcript, or quoted observation. Signal storage is unmetered; a direct quoted add can also trigger a one-credit lookup.

terminal

$ npx --yes relayai-cli@latest add "Enterprise admins need actor-level audit filtering"

Create and review your first plan

Describe an outcome, not an implementation. Open PLAN.md and review its evidence, Non-goals, files, acceptance criteria, and unresolved items.

terminal

$ npx --yes relayai-cli@latest plan "add actor filtering to the audit log"

Setup is complete when

The brain is READY and fresh, coverage is PASS, and your first PLAN.md cites real evidence and real repository paths. Review the plan before an agent implements it.

Customers do not need provider keys

Do not put OpenAI, LiteLLM, Anthropic, or E2B credentials in a customer repository. Hosted provider credentials belong on the Relay service.

THE COMPLETE LOOP

From customer words to merge evidence.

The plan is not the finish line. Version 0.10.3 carries the workflow through implementation, verification, and reviewable learning.

Signal

Retain what a customer or teammate actually said.

relayai-cli add "customer statement"

Plan

Turn one desired outcome into a cited build contract.

relayai-cli plan "desired outcome"

Review

Resolve contradictions and correct the plan with human direction.

relayai-cli comment plan/<slug> "note"

Build

Let your coding agent implement the reviewed PLAN.md.

relayai-cli run -- codex exec "Implement PLAN.md"

Verify

Run normal tests, then inspect the product report and CI gate.

relayai-cli verify --base origin/main

Learn

Turn a confirmed failure into a draft regression check.

relayai-cli learn finding_<id>

Founder or product owner

Supplies evidence, resolves trade-offs, approves scope, and makes business decisions.

Relay

Maps evidence, selects context, creates the contract, and reports declared proof.

Agent or developer

Implements the reviewed plan, explains deviations, and writes or updates tests.

Tests, CI, and reviewer

Prove behavior, security, build health, usability, and whether the change should merge.

REVIEW THE CONTRACT

What to look for in PLAN.md.

A current plan is bound to an exact brain generation, repository snapshot, and context-pack hash. Its factual claims cite customer signal, repository facts, or explicit human direction.

PLAN.md · shortened schema-v2 example

schema_version: "2"
generation_hash: 8f4b…
snapshot_hash: 2a17…
context_pack_hash: b930…

# Filter the audit log by actor

## Why now—evidence
- Compliance cannot use the audit log without this. [signal:sig_9015e031]

## Non-goals—do not build
- Do not add date-range or action-type filters.

## Acceptance criteria
1. Filtering returns only the selected actor's entries. [signal:…, fact:…]

## Implementation steps
1. modify src/app/api/audit/route.ts (expected sha256 …)
2. create src/app/api/audit/route.test.ts (must be absent)

Goal

Is the outcome stated clearly enough that a customer could recognize it?

Evidence

Does the plan cite the right customer signal and repository facts?

Non-goals

Is the agent explicitly told what not to build?

File operations

Are the named paths real and the create/modify/delete actions sensible?

Acceptance criteria

Can each item be observed or tested?

Risk

Are authorization, money, data, migrations, and failure cases handled when relevant?

Stop on unresolved constraints

Do not hand the plan to an agent while a meaningful item says UNRESOLVED. Record human direction with relayai-cli comment plan/<slug> "…", then review the new plan version.

CHECK THE CHANGE

Verification is evidence, not a magic green light.

Run your repository's normal tests, build, lint, security checks, and human review. Then use Relay to check the declared product contract.

Readable review report

$ npx --yes relayai-cli@latest verify --base origin/main

Machine-enforceable CI result

$ npx --yes relayai-cli@latest gate --base origin/main

PASSDeclared evidence passed.

PASS WITH WARNINGSReview the warnings before merge.

ACTION REQUIREDA human must provide evidence or a decision.

BLOCKEDA hard requirement failed. Do not merge.

INCOMPLETERelay cannot see enough proof to decide.

Configure the gate before trusting it

The default local configuration does not require a plan, semantic checking is off, and JUnit locations are not configured. Ask an engineer to review and commit .scriptonia/config.yaml, declare the evidence your CI produces, and enable gate in CI.

verify produces the human-readable report. gate provides enforcement. Default deterministic verification is local and free; optional semantic criteria are explicitly enabled and metered.

HOW IT UNDERSTANDS CODE

The Deep Brain is a local repository map—not a chat summary.

It builds an ignore-aware census, detects the stack and manifests, parses supported languages structurally, connects symbols and imports, maps tests, inspects bounded Git evidence, and stores everything in an immutable generation.

Local source of truth.scriptonia/brain.db

Human-readable views.scriptonia/REPO.md, GRAPH.md, ARCHITECTURE.md, PATTERNS.md

Safety ruleA failed candidate never replaces the last READY generation.

Freshness rulePlans and context must match the current repository snapshot.

Build choice	Use it when	Hosted model
`init` or `brain build --fast --offline`	First setup or a quick structural rebuild	No
`brain build --offline`	Refreshing an existing local brain after normal code changes	No
`brain build --deep --offline`	Full deterministic mapping without model explanations	No
`brain build --deep`	Adding citation-checked architecture, pattern, and decision-candidate knowledge	Yes

What do READY, fresh, and coverage PASS actually prove?

READY means a complete candidate passed brain activation checks.

Fresh means its snapshot still matches the current repository state.

Coverage PASS means required mapping and integrity checks passed.

None of these proves every behavior is correct or the application is production-ready.

Offline is still real

An offline brain still contains deterministic repository structure and evidence. It skips hosted knowledge extraction; it does not fall back to a shallow file list. The broader product workflow is not fully offline because hosted signal and plan commands still need the service.

DATA AND COST

Know what stays local, what is hosted, and what is optional.

Relay is local-first for repository analysis and deterministic verification. It is hosted where cross-project product memory and synthesis are needed.

ON YOUR MACHINE

Repository evidence

Deep Brain database and projections
Git diff and repository snapshot
PLAN.md and AGENTS.md
Local decisions and regression evals
Default deterministic verification

SCRIPTONIA SERVICE

Product memory and synthesis

Customer signal you choose to submit
Account, project, and credit metering
Product-memory search and enrichment
Plan synthesis from a bounded context pack
Connected Deep Brain fact bundle

EXPLICIT OPT-IN

Additional model evidence

Semantic verification evidence
Bounded, credential-screened inputs
Separate server-side sandbox execution when enabled

Credit guide for 0.10.3

Add a file or piped signal0 credits

Automatic enrichment, when it runs1 credit

Query product memory1 credit

Comment on a hosted context1 credit

Generate or comment on a plan5 credits

One connected Deep Brain extraction5 credits

One optional semantic criterion5 credits

Optional sandbox execution, when enabled2 credits

A normal connected Deep Brain build requests three knowledge documents, so it normally uses 15 credits. Local deterministic brain work and verification are free. Check your live balance with scriptonia credits; see current pricing for plan allowances.

Two decision planes in 0.10.3

Local policies created with scriptonia decide are used by local verification. Hosted plan decisions and comments are used during hosted planning. They are not automatically synchronized yet, so do not assume recording a rule in one plane makes it active in the other.

USE YOUR EXISTING AGENT

Relay surrounds the coding agent—it does not replace it.

Initialization writes a reviewable AGENTS.md contract. Claude Code also receives a skill; other agents can read PLAN.md or AGENTS.md, and MCP-native clients can connect over stdio.

Claude Code

Skill + AGENTS.md

scriptonia skill

Codex, Cursor, Hermes

PLAN.md + AGENTS.md

Ask the agent to implement the reviewed PLAN.md and respect its Non-goals and unresolved gates.

codex exec "Implement PLAN.md"

MCP-native clients

Hosted product tools

Use your stored Relay login to expose product context and source-linking tools.

npx --yes relayai-cli@latest mcp

Optional: capture an agent command

$ npx --yes relayai-cli@latest run -- codex exec "Implement PLAN.md exactly"

Run capture is not a sandbox

The child command inherits your terminal environment and authority, and the exact argument list is stored locally. Never put passwords or tokens in command arguments.

COMMAND REFERENCE

Find the command you need.

The quickstart above is enough for a first result. Open these groups only when you need a specific operation.

0.10.3 option syntax

For legacy hosted commands, keep option values in --flag=value form, such as --segment=enterprise or --as="Product owner".

Setup and account

Use these when installing, signing in, or checking the active project.

relay doctor

Offline runtime and brain diagnosis.

relay login

Browser sign-in; stores account credentials locally and installs the Claude skill.

relayai-cli init --about="…"

Bind the exact committed Git root and build its first brain.

relay status

Show signed-in account, endpoint, and active project.

relay credits

Show plan, balance, and reset date.

relay logout

Remove the stored Relay session.

Deep Brain and local memory

Use these to build, inspect, and explain repository context.

relayai-cli brain status --check

Exhaustively compare the repository with the active generation; read its fresh/stale and coverage results.

relayai-cli brain build --offline

Refresh an existing brain locally.

relayai-cli brain build --deep --offline

Run the full deterministic pipeline without hosted knowledge.

relayai-cli brain build --deep

Add citation-checked connected knowledge.

relayai-cli brain context "<task>"

Build a local, freshness-checked context pack for one task.

relayai-cli why <path-or-symbol>

Explain impact, tests, decisions, and evals affecting a target.

relay pulse

Quick local overview of brain, repo, decisions, evals, and recent runs.

scriptonia recall "<query>"

Search local decisions and evals.

Customer signal and plans

Use these for hosted product memory and the plan-review loop.

relayai-cli add <files-or-text>

Add customer evidence. Supports files, quoted text, or piped stdin.

scriptonia query "<topic>"

Quick product-memory lookup without a full plan.

relayai-cli plan "<outcome>"

Create the cited schema-v2 PLAN.md.

relay plans

List existing plan slugs and versions.

relayai-cli comment plan/<slug> "…"

Record human direction and regenerate a new plan version.

relayai-cli link <signal-id>

Retrieve the original text behind a signal reference.

scriptonia contexts

List themes synthesized from hosted product signal.

relay sync

Refresh local product-memory projections and managed instructions.

Build, verify, and learn

Use these after the plan is reviewed.

relayai-cli run -- <agent-command>

Capture the exact agent command and local run evidence.

relay runs

List captured local agent runs.

relayai-cli verify --base origin/main

Produce the complete human-readable local evidence report.

scriptonia gate --base origin/main

Aggregate evidence into a machine-enforceable CI status.

relayai-cli learn finding_<id>

Convert a confirmed finding into a reviewable draft eval.

scriptonia eval doctor

Validate versioned regression-case definitions.

scriptonia eval run

Run active regression cases.

scriptonia decide "<title>"

Create a reviewable local product or architecture decision.

Agent integration

Use these when wiring compatible coding tools.

scriptonia skill

Reinstall the Claude Code skill.

scriptonia mcp

Run the hosted product-memory MCP server over stdio.

scriptonia --help

Print the installed command overview.

MULTIPLE REPOSITORIES

One exact Git root, one repository brain.

Initialize every repository separately. Repository analysis lives inside that repository's .scriptonia/brain.db; the home-directory project folder is the local surface for hosted product-memory receipts and projections.

terminal

$ cd ~/code/product-a && npx --yes relayai-cli@latest init
$ cd ~/code/product-b && npx --yes relayai-cli@latest init
$ cd ~/code/product-a && npx --yes relayai-cli@latest brain status --check

Relay rejects mismatched parent, child, or sibling roots instead of silently selecting another repository's brain.

TROUBLESHOOTING

Start with the error you can see.

These fixes preserve the last known-good brain and avoid destructive recovery steps.

I have the wrong version or no brain command

What it means: The npm tag or cached package is older than the stable release.

terminal

$ npx --yes relayai-cli@latest --version

Then: The expected stable version for this guide is 0.10.3. Use @latest, not @next.

Relay says this is the wrong repository

What it means: The current directory does not match the exact Git root that was initialized.

terminal

$ git rev-parse --show-toplevel
$ cd /the/exact/path/printed/above

Then: Do not force-initialize a parent, nested child, or sibling to bypass the guard.

The brain is missing or stale

What it means: No active generation matches the current repository snapshot.

terminal

$ npx --yes relayai-cli@latest brain build --offline
$ npx --yes relayai-cli@latest brain status --check

Then: For a first structural rebuild, use --fast --offline.

A connected deep build failed or timed out

What it means: The enrichment candidate failed; the last READY generation is preserved.

terminal

$ npx --yes relayai-cli@latest brain status --check
$ npx --yes relayai-cli@latest brain build --deep --offline

Then: Do not delete .scriptonia/brain.db. Retry the connected build once if needed.

Plan returned HTTP 422 or a schema error

What it means: The service rejected invalid structured output. It is not proof that your repository is broken.

terminal

$ npx --yes relayai-cli@latest --version

Then: Retry the same plan once. If it repeats, send support the request ID and full error.

Verification says INCOMPLETE

What it means: Required proof is missing or has not been configured.

terminal

$ npx --yes relayai-cli@latest verify --base origin/main --refresh

Then: Run your normal checks, expose their declared evidence, confirm the Git base, and verify again.

Node or SQLite failed after an upgrade

What it means: The installed native module may no longer match the Node runtime.

terminal

$ npx --yes relayai-cli@latest doctor

Then: Follow the exact reinstall or rebuild remedy that doctor prints. Deleting the brain will not repair Node.

What to send support

Include your Relay version, the exact command, the complete error, your operating system and Node version, and the request ID when one is shown. Do not send API keys, tokens, or private customer data.

FAQ

Questions customers ask before they trust the loop.

Do I need to know how to code?

You do not need to write code to add customer evidence, generate a plan, or review scope. A coding agent or developer implements the plan. An engineer should still configure tests and the CI gate.

Does Relay write the code?

No. Claude Code, Codex, Cursor, Hermes, another coding agent, or your developers write the code. Relay supplies grounded context, a build contract, and verification evidence.

Does a READY brain mean my product is production-ready?

No. READY means one repository brain generation passed its activation checks. It does not prove that the application is secure, correct, or ready to deploy.

Does verification replace tests or CI?

No. Run the repository's normal tests, build, lint, security checks, and human review. Relay verifies the declared product contract and consumes evidence you configure; it does not automatically execute repository commands.

Can I work completely offline?

Brain building, context selection, and deterministic verification have offline paths. Adding hosted product signal, searching it, and generating or commenting on hosted plans still require login and internet access.

Can I edit PLAN.md by hand?

You can, but a later regeneration can overwrite the edit. Use a plan comment when the change should be retained as human direction and included in the next plan version.