User Guide

A walk-through from zero to a reviewed AI system. All commands run offline.

1. Check your machine

npx governsutra-ai doctor

Expect nodeSupported: true and runtimeDependencies: 0.

2. Create a workspace

governsutra init

This creates .governsutra/ (registry, policies, evidence index, audit log). Add .governsutra/ to .gitignore if it holds anything sensitive; it normally holds metadata only.

3. Describe an AI system

Create my-system.json (start from fixtures/sample-system.json). Required: id, name, intendedUse, owner, riskOwner, and arrays models, tools, dataSources, humanCheckpoints, prohibitedUses (use [] to declare none). Unknown values should be written as unknown, not guessed.

governsutra register --input my-system.json

4. Assess

governsutra assess --id MY-SYSTEM-1 --format md

Read the rules table first. fail means a declared gap. unknown means no evidence either way. not-applicable is explained. The decision line always says HUMAN_REVIEW_REQUIRED.

5. Attach evidence

governsutra evidence add --id MY-SYSTEM-1 --file docs/model-card.md --kind model-card --expires 2027-06-30 --verifier "Jane Reviewer"
governsutra evidence verify

Only a hash is stored. If the file changes, goes missing or expires, evidence verify reports it and exits 2. Then list the evidence ID under a control with status verified-by-named-reviewer and a verifier to satisfy GOV-004.

6. Discover candidates in a repository

governsutra scan --repo ../my-app

Open .governsutra/scans/latest.json. These are observed candidates, not an inventory. Confirm with the owner, then register a system or commit an owner manifest.

7. Keep manifests in the repository

Put governance/ai-systems/my-system.json in the repo (optionally with integrity.sha256). Then:

governsutra import-manifests --repo ../my-app

8. Detect change

governsutra diff --a last-quarter.json --b today.json --format html > change.html

Triggers such as model-change-review or tool-permission-review tell a human what to re-review.

9. Record an exception (human only)

Add to the system record:

"exceptions": [{"id":"EX-1","ruleId":"GOV-006","rationale":"Pilot, reviewed daily","scope":"staging only",
  "approver":{"name":"Jane Doe","type":"human"},"expiresAt":"2027-01-31"}]

The rule shows exception-approved until expiry, then fails again.

10. Produce reports

governsutra report --id MY-SYSTEM-1 --out ./reports/my-system-1
governsutra audit --out ./audit --force
governsutra verify --report ./audit/audit-report.json

You get JSON, Markdown and HTML for each.

11. Use with an AI IDE

governsutra install-ide --host cursor --target . --dry-run
governsutra install-ide --host cursor --target .

Existing files are never overwritten without --force. Native behavior depends on the IDE and version.

Troubleshooting

SymptomCause and fix
Invalid system: ... must be an arrayDeclare [] for none.
System already existsIDs are unique; use diff to review a changed record.
Refusing to overwriteReview the target, then pass --force.
Secret-like paths cannot be attachedAttach documentation about the secret store, not the secret.
serve asks for a tokenGOVSUTRA_TOKEN must be 24+ random characters.
Symlink checks skipped on WindowsWindows needs privilege to create file symlinks; the check is reported as skipped, not passed.