See RuleOak decide before execution

The source repository is the baseline quickstart. Published npm packages, when available, are a convenience distribution path rather than a prerequisite for understanding or verifying the release.

Requirements

• Node.js 22 or later
• Git and a local terminal

1. Run from the public source repository

git clone https://github.com/ruleoak/ruleoak.git
cd ruleoak
git checkout v0.50.0
npm ci --ignore-scripts
node packages/cli/bin/ruleoak.js demo quickstart

The demo creates a temporary local workspace, produces allow / approval-required / deny decisions, a redacted evidence log and an offline HTML report. It does not make destructive or external calls.

2. Prove the Effect Boundary failure mode

node packages/cli/bin/ruleoak.js demo effect-boundary

The scenario deliberately performs a local filesystem write and then loses the execution response. RuleOak independently checks the resulting digest. A confirmed postcondition becomes confirmed_success → do_not_retry; no duplicate write is issued.

3. Get an activation plan

node packages/cli/bin/ruleoak.js onboard --init

Onboarding uses bounded project detection and reports the activation stage and next command.

4. Inspect protection setup without mutation

node packages/cli/bin/ruleoak.js protect --setup --dry-run

5. Activate a supported MCP stdio route

node packages/cli/bin/ruleoak.js protect --setup --apply
node packages/cli/bin/ruleoak.js protect check
node packages/cli/bin/ruleoak.js protect check --require-effect-boundary

READY_EFFECT_BOUNDARY means route interception and trusted effect-profile semantics are both available. READY_POLICY_ONLY means policy/interception is healthy but postcondition certainty is not available for at least one route.

6. Guard a real process

node packages/cli/bin/ruleoak.js protect -- node agent.js

# MCP server with a conservative policy pack
node packages/cli/bin/ruleoak.js protect --policy-pack mcp-server-safe -- node mcp-server.js

protect covers supported traffic crossing the RuleOak boundary. It does not inspect arbitrary hidden behavior inside the child process.

7. Inspect local state

node packages/cli/bin/ruleoak.js doctor
node packages/cli/bin/ruleoak.js workspace status
node packages/cli/bin/ruleoak.js policy lint
node packages/cli/bin/ruleoak.js replay --verify

8. Recover an uncertain effect without replaying it

node packages/cli/bin/ruleoak.js effect pending
node packages/cli/bin/ruleoak.js effect reconcile --limit 20
node packages/cli/bin/ruleoak.js effect show --id <effect-id>
node packages/cli/bin/ruleoak.js effect retry-plan --id <effect-id>

Reconciliation reruns bounded postcondition checks. It does not replay the original action. Any retry requires fresh one-use authority.

9. Verify the release and local evidence

npm run check:publish
node packages/cli/bin/ruleoak.js audit bundle --out ruleoak-evidence.zip
node packages/cli/bin/ruleoak.js audit verify-bundle --file ruleoak-evidence.zip
node packages/cli/bin/ruleoak.js record verify

Optional npm distribution

If and only if the exact @ruleoak/cli@0.50.0 package is publicly available and its packed contents have been verified, the equivalent convenience form is:

npx @ruleoak/cli@0.50.0 demo quickstart