docs(readme): expand stub README to full structure

[hyperpolymath]

Summary

Expands the previous stub README (< 20 lines) into a substantive README covering: project description, layout, quickstart, status, and companion-repo cross-references. Grounded in this repo's actual content; no fabricated features.

Closes Row-2 Phase 1 of the 2026-05-26 estate tech-debt audit chain (covers this repo's HIGH-severity finding from standards#197).

Companion

• standards#197 — estate documentation-debt audit (the audit that flagged this).
• rsr-template-repo#75 — the docs-template/ seed this README's structure mirrors.

🤖 Generated with Claude Code

[github-actions]

🔍 Hypatia Security Scan

Findings: 29 issues detected

Severity	Count
🔴 Critical	3
🟠 High	19
🟡 Medium	7

⚠️ Action Required: Critical security issues found!

View findings

[
  {
    "reason": "Issue in codeql.yml",
    "type": "missing_workflow",
    "file": "codeql.yml",
    "action": "create",
    "rule_module": "workflow_audit",
    "severity": "high"
  },
  {
    "reason": "Issue in scorecard.yml",
    "type": "missing_workflow",
    "file": "scorecard.yml",
    "action": "create",
    "rule_module": "workflow_audit",
    "severity": "high"
  },
  {
    "reason": "Action hyperpolymath/standards/.github/workflows/governance-reusable.yml@main needs attention",
    "type": "unpinned_action",
    "file": "governance.yml",
    "action": "pin_sha",
    "rule_module": "workflow_audit",
    "severity": "high"
  },
  {
    "reason": "Required file missing (condition: public_repo)",
    "type": "missing_requirement",
    "file": ".github/workflows/scorecard.yml",
    "action": "create",
    "rule_module": "cicd_rules",
    "severity": "high"
  },
  {
    "reason": "Hardcoded credential in Nickel config -- use SecretRef (2 occurrences, CWE-798)",
    "type": "ncl_hardcoded_secret",
    "file": "/home/runner/work/flatracoon/flatracoon/netstack/configs/environments.ncl",
    "action": "flag",
    "rule_module": "code_safety",
    "severity": "critical"
  },
  {
    "line": 70,
    "reason": "Secret found: Generic secret",
    "type": "secret_detected",
    "file": "/home/runner/work/flatracoon/flatracoon/netstack/configs/environments.ncl",
    "action": "revoke_rotate_and_purge",
    "rule_module": "security_errors",
    "severity": "critical"
  },
  {
    "line": 108,
    "reason": "Secret found: Generic secret",
    "type": "secret_detected",
    "file": "/home/runner/work/flatracoon/flatracoon/netstack/configs/environments.ncl",
    "action": "revoke_rotate_and_purge",
    "rule_module": "security_errors",
    "severity": "critical"
  },
  {
    "reason": "Js.Dict deprecated -- use Dict (14 occurrences)",
    "type": "deprecated_api",
    "file": "/home/runner/work/flatracoon/flatracoon/netstack/interface/src/FlatRacoonClient.res",
    "action": "module_replace",
    "rule_module": "migration_rules",
    "severity": "high"
  },
  {
    "reason": "Js.Json deprecated -- use JSON (31 occurrences)",
    "type": "deprecated_api",
    "file": "/home/runner/work/flatracoon/flatracoon/netstack/interface/src/FlatRacoonClient.res",
    "action": "module_replace",
    "rule_module": "migration_rules",
    "severity": "medium"
  },
  {
    "reason": "Nominal-only SAST in flatracoon: codeql.yml language matrix contains no language present in the repo and lacks `actions`, so CodeQL records zero results on every commit. Remediation: set the CodeQL matrix to `language: actions`.",
    "type": "StaticAnalysis",
    "file": "/home/runner/work/flatracoon/flatracoon",
    "action": "auto_fix",
    "rule_module": "scorecard",
    "severity": "medium",
    "remediation": "Add CodeQL or equivalent SAST workflow.",
    "scorecard_check": "SAST"
  }
]

Powered by Hypatia Neurosymbolic CI/CD Intelligence