Complete setup
every path

Start

Choose your path

Compatible tools

Which AI tools can use Seal?

Seal is a command-line workflow for Jira tickets and test evidence. It does not replace your chat app or editor — it runs alongside them.

Prerequisites

What you need

Paths

Symbols the agent uses

CLI for all commands:

node <SEAL_ROOT>/product/bin/seal.mjs <command>

Agent playbook

How the Cursor agent must behave

1. One phase at a time. Finish the phase, show pass/fail, then ask "Ready for the next step?"
2. Run commands yourself in the terminal. Do not tell the user to copy-paste unless they must enter secrets.
3. Ask for secrets — greenfield installs have no pre-filled .env. Run seal setup after each step.
4. Phases 0–8: no seal open / seal done. Only Phase 9 runs the verification cycle.
5. Phase 9 must use evidence workflow — evidence, test, attach, then done with facts. Never close with only open + done.
6. End with a delivery card — Jira ticket URL, browser checklist, memory ref if Orchestra ran.
7. After setup, normal rules in .cursor/rules/seal.mdc apply (including policy checks).

Greenfield

First-time prep (before Cursor)

cd D:\BertaSeal
powershell -ExecutionPolicy Bypass -File scripts/prepare-first-time.ps1

Cursor

Paste into Cursor Agent chat

SIMULATION: I am a first-time Berta Seal customer. Nothing is pre-configured for me.

Rules for this session:
- Use BERTA_SEAL_HOME=D:/FirstSealUser/.berta-seal for ALL seal commands
- Do NOT read or use %USERPROFILE%\.berta-seal — it is from another user/dev setup
- Do NOT assume D:/mix/jira-berta/.jira-berta.env is mine — ASK me for Jira URL, email, API token and CREATE the file from product/templates/jira-berta.env.example
- Run seal setup after every phase; show me ✗/✓
- One phase at a time; wait for my OK
- Follow Phases 0–10 in setup-guide.html (or docs/GETTING-STARTED.md)

My sandbox (empty new project): D:/FirstSealUser
Seal CLI: D:/BertaSeal/product/bin/seal.mjs

Phase 9 must complete: seal open → seal evidence → seal test --run → seal attach → seal done with Jira subtask.

I will paste Jira credentials when you ask. Start with Phase 0.

Retest Berta Seal from Phase 9. seal setup passes on my machine.
Sandbox: D:/YourProject
Seal CLI: D:/BertaSeal/product/bin/seal.mjs
Run open → evidence → test --run → attach → done on a new ticket.

Add Berta Seal to this project:
- CLI: node D:/BertaSeal/product/bin/seal.mjs
- Start: seal policy check open → seal open "<user request>"
- Work: seal evidence, seal test --run --command "npm test"
- End: seal policy check done → seal done "<outcome>"
- Configure ~/.berta-seal/programmes.json with all my repo paths and Jira projects.
- Run test cycle and give me the Jira ticket URL.

Setup phases

Phases 0–8 — install (no Jira tickets yet)

node -v
node <SEAL_ROOT>/product/bin/seal.mjs setup --sandbox <SANDBOX>

node <SEAL_ROOT>/product/bin/seal.mjs setup --scaffold-jira-env --jira-root D:/mix/jira-berta
Test-Path D:/mix/jira-berta/bin/jira-berta.mjs

JIRA_BASE_URL=https://THEIR-SITE.atlassian.net
JIRA_EMAIL=their@email.com
JIRA_API_TOKEN=their_token

node <SEAL_ROOT>/product/bin/seal.mjs setup --jira-root D:/mix/jira-berta
node D:/mix/jira-berta/bin/jira-berta.mjs ledger --limit 1

cd <SEAL_ROOT>
node product/bin/seal.mjs init --target <SANDBOX>
node product/bin/seal.mjs setup --sandbox <SANDBOX>

{
  "version": 1,
  "seats": 1,
  "jiraBertaRoot": "D:/mix/jira-berta",
  "orchestraUrl": "http://localhost:4317",
  "programmes": [{
    "id": "myapp",
    "label": "My App",
    "path": "D:/path/to/SANDBOX",
    "emoji": "🚀",
    "jiraProject": "PROJECT_KEY",
    "sealPolicy": "ask"
  }]
}

node <SEAL_ROOT>/product/bin/seal.mjs setup --sandbox <SANDBOX>

node <SEAL_ROOT>/product/bin/seal.mjs init --target <SANDBOX>

curl -s -o NUL -w "%{http_code}" http://localhost:4317/api/health

cd <SANDBOX>
node <SEAL_ROOT>/product/bin/seal.mjs health

Verification

Phase 9 — Full evidence verification (mandatory)

Proof that Seal works. Jira must show facts, tests, attachments, and To Do → In Progress → Done.

cd <SANDBOX>
mkdir .seal-evidence -Force
node <SEAL_ROOT>/product/bin/seal.mjs open "Berta Seal setup verification — evidence workflow"

Show user ticket key (e.g. SEALTEST-10) and browse URL. Confirm status is In Progress.

9a — Work + proof file

$ts = (Get-Date).ToUniversalTime().ToString("o")
Add-Content -Path README.md -Value "`nVerified: $ts"
$log = ".seal-evidence/setup-verify-$(Get-Date -Format 'yyyyMMdd-HHmmss').log"
"Setup verification log`nTimestamp: $ts`nSandbox: <SANDBOX>" | Out-File -Encoding utf8 $log

9b — Document facts

node <SEAL_ROOT>/product/bin/seal.mjs evidence "Setup change applied" `
  --fact "README updated with ISO timestamp" `
  --fact "Proof log under .seal-evidence/"

9c — Automated test (creates subtask)

node <SEAL_ROOT>/product/bin/seal.mjs test "Seal health check" --run `
  --command "node <SEAL_ROOT>/product/bin/seal.mjs health" `
  --agent cursor

Note the subtask key printed (e.g. SEALTEST-11).

9d — Attach deliverable

node <SEAL_ROOT>/product/bin/seal.mjs attach .seal-evidence/<your-log>.log `
  --body "Setup verification proof log"

9e — Close with delivery evidence

node <SEAL_ROOT>/product/bin/seal.mjs done "Berta Seal setup complete — full evidence trail verified" `
  --fact "Workflow: open → evidence → test → attach → done" `
  --fact "Subtask created on PASS" `
  --attach .seal-evidence/<your-log>.log

9f — Verify in Jira (browser checklist)

seal status must show no active session.

Give user: Jira URL · configured paths · daily ritual (seal open → work → seal done) · this guide URL.

Handoff

Phase 10 — Normal operation

Every request after setup (not only install):

seal policy check open                    # ask / always / never
seal open "<request>"                     # To Do → In Progress
seal evidence "<fact>" --fact "..."       # documented facts
seal test "<name>" --run --command "..."   # subtask + log
seal attach file.md                       # deliverables
seal policy check done
seal done "<shipped>" --fact "..."        # Done + delivery evidence

More repos: add to programmes.json and seal init --target <repo>. Use Admin panel to manage programmes and policies.

Expert

Hands-on (expert) setup

You edit files and run commands directly — follow Phases 0–9 above without an agent.

# 1. Jira
copy product\templates\jira-berta.env.example D:\mix\jira-berta\.jira-berta.env
node D:\mix\jira-berta\bin\jira-berta.mjs ledger --limit 1

# 2. Seal config
node product\bin\seal.mjs init
notepad %USERPROFILE%\.berta-seal\programmes.json

# 3. Each project repo
node product\bin\seal.mjs init --target D:\Projects\MyApp

# 4. Policies
node product\bin\seal.mjs policy set --global ask

# 5. Verify (from project cwd)
node D:\BertaSeal\product\bin\seal.mjs health
node D:\BertaSeal\product\bin\seal.mjs open "Expert setup test"
node D:\BertaSeal\product\bin\seal.mjs test "tests" --run --command "npm test"
node D:\BertaSeal\product\bin\seal.mjs done "Expert path verified"

Admin panel → import/generate programmes.json and policies.json.

Projects

Multi-project — any repo you assign to Seal

Add every workspace to programmes.json. Unlimited programmes; license limits seats only.

{
  "version": 1,
  "seats": 5,
  "jiraBertaRoot": "D:/mix/jira-berta",
  "orchestraUrl": "http://localhost:4317",
  "programmes": [
    { "id": "myapp", "label": "My App", "path": "D:/Projects/myapp", "emoji": "🚀", "jiraProject": "MYAPP", "sealPolicy": "always" },
    { "id": "client", "label": "Client X", "path": "D:/Clients/x", "emoji": "🏢", "jiraProject": "CLIENTX", "sealPolicy": "ask" },
    { "id": "scratch", "label": "Experiments", "path": "D:/Scratch", "emoji": "🧪", "jiraProject": "LAB", "sealPolicy": "never" }
  ]
}

seal init --target <path> in each repo installs .cursor/rules/seal.mdc. Seal picks programme from cwd (longest path prefix match).

New Jira project: register in jira-berta/projects.json, then jira-berta bootstrap --create --only id.

Policies

Jira: global vs per-project

File: %USERPROFILE%\.berta-seal\policies.json

User phrases (when policy is ask)

seal policy                          # show rules
seal policy check open|done          # 0=proceed  2=ask agent  skip=never
seal policy set --global always|ask|never
seal policy set --programme myapp ask
seal policy remember --programme myapp always|never|clear
seal admin

Admin panel → import programmes, edit policies, copy JSON or CLI.

DevOps

Evidence & automated testing

Every delivery: parent ticket + test subtasks + ADF tables + log attachments in Jira.

SEALTEST-42  Story: Add user roles          [Done]
├── SEALTEST-43  Sub-task: Test: unit tests  [Done]  ← seal test --run
├── SEALTEST-44  Sub-task: Test: lint        [Done]
└── Comments: [test] tables, [test-summary], [delivery]
    Attachments: test-*.log in .seal-evidence/

Daily workflow

seal open "user request"
seal evidence "fact" --fact "…" --agent cursor
seal test "unit tests" --run --command "npm test" --agent cursor
seal attach deliverable.zip
seal done "shipped" --fact "Tests PASS"

seal test --run will: run command · write log to .seal-evidence/ · create subtask · post table on parent · attach log · transition subtask Done on PASS.

seal done requires at least one test subtask unless --skip-tests (docs-only). Posts [test-summary] automatically.

Manual test (when no command exists)

seal test "manual UI review" --pass --agent human --body "Login verified" --attach screenshot.png

Multi-agent

seal test "API tests" --run --command "npm run test:api" --agent claude
seal evidence "review" --fact "Security pass" --agent copilot
# Default agent: BERTA_SEAL_AGENT=claude in sandbox .env

Support

Troubleshooting

CLI

Command summary