Skip to content

Reference

repos
+-- tech (language, framework, shape, runtime)
+-- notes (thesis, architecture, warning, convention, ...)
+-- docs (README, CHANGELOG, indexed content)
+-- facts (dependencies, config keys, endpoints)
+-- relationships (depends_on, related_to, supersedes, ...)
+-- audit_runs
+-- audit_control_results (per-control pass/fail)
+-- audit_findings (title, severity, remediation)
+-- audit_metrics (pass_rate, coverage, counts)
Type Purpose
thesis What the repo is and why it exists
architecture How it’s built, key components, data flow
convention Important patterns or rules specific to this repo
warning Known issues or things that could break
next_step What should happen next
drift_risk Things that could diverge from intended state
release_summary Summary of a release
command Key commands to build, test, deploy
pain_point Known developer experience issues
general Anything else
Type Meaning
depends_on Hard dependency
related_to Soft association
supersedes Replaces an older repo
shares_domain_with Same problem domain
shares_package_with Shared npm/pip package
companion_to Designed to work together

rk.config.json in the workspace root:

{
"owners": ["my-github-org"],
"localDirs": ["/path/to/repos"],
"dbPath": "data/knowledge.db",
"artifactsRoot": "data/artifacts"
}

The audit import contract expects a directory with these files:

{
"slug": "my-org/my-repo",
"overall_status": "pass_with_findings",
"overall_posture": "needs_attention",
"domains_checked": ["code_quality", "testing"],
"auditor": "claude",
"started_at": "2026-03-18T10:00:00Z",
"completed_at": "2026-03-18T10:05:00Z"
}
[
{ "control_id": "QUA-001", "result": "pass" },
{ "control_id": "TST-001", "result": "fail", "notes": "No tests" }
]
[
{
"domain": "testing",
"title": "No test suite",
"severity": "high",
"remediation": "Add vitest"
}
]
{
"controls_total": 80,
"controls_passed": 65,
"controls_failed": 10,
"pass_rate": 81.25,
"critical_count": 0,
"high_count": 3
}

References to raw report files on disk. Files are not imported into the database — only their metadata is stored.

[
{
"artifact_type": "eslint_report",
"path": "reports/eslint.json",
"generated_by": "eslint",
"format": "json"
}
]

Control IDs follow the pattern DOMAIN-NNN:

Prefix Domain
INV inventory
QUA code_quality
SEC security_sast
DEP dependencies_sca
LIC licenses
SCR secrets
CFG config_iac
CON containers
RUN runtime
PRF performance
OBS observability
TST testing
CIC cicd
DPL deployment
BDR backup_dr
MON monitoring
CPR compliance_privacy
SUP supply_chain
INT integrations

Use rk audit controls --domain <domain> to see all controls for a domain.

All errors from the programmatic API follow a structured shape:

Field Type Description
code string Machine-readable error code
message string Human-readable error message
hint string? Suggested fix or next step
cause string? Underlying cause
retryable boolean Whether the operation can be retried

The config is resolved in this order (later sources override earlier ones):

  1. Defaults – data/knowledge.db in CWD, no owners, local dirs = ["."]
  2. rk.config.json in CWD – merged over defaults
  3. CLI flags – --owners, --local, etc. override for that command

Relative paths in config are resolved from the current working directory.