Public documentation for governed AI labor
SDKs/Governance/Connectors
Arx / Docs / Repository layout

Documentation

Repository layout

arxsec-site / REPO_LAYOUT.md

arxsec-site repo-root REPO_LAYOUT.md

This is the public-site repository layout for arxsec.io.

The application code that used to live under arxsec-api/ now lives in the separate repo /Users/mr.frierson/arxsec-app. Do not treat this repo as the deploy source for the API or the app frontend.

Deployable surfaces

| Surface | What deploys | Where from | Triggered by | |---|---|---|---| | Marketing site | Root-level *.html files and shared static assets | Vercel | vercel.json | | Documentation site | docs/ | Vercel / docs build pipeline | docs/vercel.json | | Atlas (customer-private) | atlas/ (FastAPI + Helm chart) | Customer's K8s cluster | .github/workflows/atlas-release.yml on tag atlas/v*.*.* (cosign-signed image to GHCR; customer mirrors before deploy) | | Python SDK | sdks/agentvault-py/ | PyPI | .github/workflows/publish-agentvault.yml on tag agentvault-v* | | Application repo | /Users/mr.frierson/arxsec-app | Aptible | app repo workflows |

Don't move files in any of those paths without updating the matching deploy config.

Top-level directory map

Application code

  • Application/backend/frontend code now lives in /Users/mr.frierson/arxsec-app.
  • atlas/ — customer-private CEO aide.
  • app/ — FastAPI service with 5 capability modules
  • charts/atlas/ — Helm chart (do not restructure)
  • tests/ — pytest suite
  • RELEASING.md — cosign release pipeline
  • workforce-modeler/ — standalone FastAPI for engagement-fee

forecasts + scenario comparison.

Library + tooling

  • sdks/agentvault-py/ — published Python SDK with @governed

decorator.

  • tools/arxctl/ — CLI with validate-manifests and

verify-chain subcommands. Standalone; no deploy coupling.

  • library/ — reusable policies, prompts, workflows.

Reference agents

  • reference-agents/ — one dir per agent. 50+ agents shipped.

Each conforms to MANIFEST_FRAMEWORK.md. See INDEX.md for the 84-cell × 3-shape coverage map.

  • reference-agents/_scaffolders/ — code generators that emit

agent dirs from spec dicts. See _scaffolders/README.md.

Documentation

  • docs/ — GitBook source. TOC lives in docs/SUMMARY.md.

Notable subdirs added in the 9-phase build:

  • docs/atlas/ — Atlas spec + auditable network policy
  • docs/credentials/ — per-agent credential vault integration guide
  • docs/deployment/ — 72-hour runbook
  • docs/pricing/ — value-based pricing model
  • docs/sdk/ — SDK quickstart + worked examples per shape

Sales / marketing

  • sales-assets/ — exec briefings, value memos, board-deck

generators.

  • partners/, outreach/ — partner + customer-facing material.
  • Root-level *.html files — Vercel-deployed marketing pages

(only the 8 in vercel.json are routed; the rest are design/Figma exports).

Other

  • .github/workflows/ — CI/CD.
  • examples/, poc/, benchmark/, load-tests/ — eval +

prototyping.

  • scripts/ — one-off operational scripts.

Where to put a new file

| You're adding... | Put it in... | |---|---| | A new backend route | /Users/mr.frierson/arxsec-app/app/api/v1/<name>.py + register in /Users/mr.frierson/arxsec-app/main.py | | A new domain module | /Users/mr.frierson/arxsec-app/app/core/<name>.py | | A new connector adapter | /Users/mr.frierson/arxsec-app/app/connectors/<name>.py | | A new dashboard page | /Users/mr.frierson/arxsec-app/frontend/src/app/(dashboard)/<route>/page.tsx + nav entry in /Users/mr.frierson/arxsec-app/frontend/src/components/sidebar.tsx | | A new Atlas capability | atlas/app/capabilities/<name>.py + dispatch in atlas/app/main.py | | A new reference agent | reference-agents/<function>-<level>-<shape>-<short-name>/ matching the canonical structure | | A new scaffolder | reference-agents/_scaffolders/_scaffold_<name>.py with ROOT = Path(__file__).resolve().parent.parent | | A new arxctl subcommand | tools/arxctl/<name>.py + register in tools/arxctl/__main__.py | | New documentation | docs/<topic>/<name>.md + entry in docs/SUMMARY.md | | A new migration | /Users/mr.frierson/arxsec-app/supabase/migrations/<timestamp>_<name>.sql (keep timestamp ordering) |

Where NOT to put files

  • Don't add code at the repo root. Put it in the right top-level

dir.

  • Don't add another arxsec/ or lib/ at the repo root — those

legacy dirs predate this layout and shouldn't grow.

  • Don't add new HTML files at the repo root unless you also

update vercel.json to route them.

  • Don't add a parallel docs tree (docs-pages/, engineer-docs/,

getting-started/ already exist as legacy holdovers; new docs go in docs/ only).

Operational story

For the operational walkthrough — Atlas → manifest set → cohort instantiation → 72-hour deployment runbook — start at docs/deployment/72-hour-runbook.md.

For the trust artifacts a customer's CISO needs — Atlas trust posture, audit chain verification, per-agent credential attribution — start at docs/atlas/atlas-spec.md and docs/credentials/per-agent-auth-integration.md.

For pricing — docs/pricing/value-based-pricing.md.

For building agents on the framework — docs/sdk/README.md plus the three worked examples (research / production / coordination).