Documentation Index
Fetch the complete documentation index at: https://atlas.devarno.cloud/llms.txt
Use this file to discover all available pages before exploring further.
Archive System v2.0 Runbook
What Is the Archive System?
The /archive system captures knowledge from AI-assisted work sessions and routes it to the correct repository based on content type. When you run /archive, the system reads a central registry to discover all participating repos, reads each repo’s self-describing manifest to learn what it accepts, then generates and commits documents with bidirectional cross-references.
This repo (atlas) stores two content types:
- Learnings — business-facing takeaways from engineering sessions (
learnings/ directory)
- Campaigns — marketing and GTM content (
campaigns/ directory)
The authoritative schema for what atlas accepts is defined in .archive-manifest.yaml at the repo root.
The 5-Repo System
| Repo | Org | What It Stores | Audience |
|---|
| atlas (this repo) | devarno-cloud | Business learnings + marketing campaigns | Business / Marketing |
| so1-content | so1-io | Technical findings (bugs, patterns, decisions) | Engineering |
| veritas | so1-io | Reusable prompts (quarantined before promotion) | Engineering |
| ariel | traceo-ai | Frozen baselines + specs (MkDocs site) | Engineering |
| traceo-mcp-server | traceo-ai | MCP server (receives baselines via ariel pip dependency, never written directly) | — |
How It Works
1. Discovery
The /archive command reads ~/.config/opencode/archive-registry.yaml to find all registered repos and their local paths. It then reads .archive-manifest.yaml from each repo to learn:
- What content types the repo accepts
- Where to put files (path templates)
- What frontmatter fields are required
- Word limits, audience, and validation rules
2. Classification
Session content is classified into types. The type determines which repo receives it:
| If the session produced… | Type | Goes to |
|---|
| A bug fix or technical decision | finding + learning (paired) | so1-content + atlas |
| A business insight | learning | atlas |
| A marketing asset | campaign | atlas |
| A reusable prompt | prompt | veritas |
| An architecture freeze | baseline | ariel |
| A spec change | spec | ariel |
3. Document Generation
For atlas, documents are generated per the manifest:
Learnings: placed at learnings/{YYYY-MM-DD}-{slug}.md, max 500 words, business audience. Required frontmatter: title, date, type: learning, tags, source_session. Optional: cross_ref, roz_id, audience, business_impact.
Campaigns: placed at campaigns/{YYYY-MM-DD}-{slug}.md, max 500 words, marketing audience. Same required frontmatter with type: campaign.
4. Cross-Referencing
Every document’s frontmatter includes a cross_ref: array linking to every other document produced in the same /archive invocation. The canonical format:
cross_ref:
- repo: so1-io/so1-content
path: findings/2026-03-17-example.md
type: finding
5. Commit + Push
All commits use local git (not GitHub Contents API). Atlas is committed after so1-content, in parallel with veritas.
Verifying an Archive
After /archive runs, verify the results:
Check the files landed correctly
# From the atlas repo root:
ls -la learnings/ # Latest file should be today's date
ls -la campaigns/ # If a campaign was produced
Verify frontmatter is valid
# Quick check that a file has the required fields:
head -20 learnings/2026-03-22-example.md
---
title: "..."
date: "2026-03-22"
type: learning
tags: [tag1, tag2]
source_session: "archive-2026-03-22-example"
cross_ref:
- repo: so1-io/so1-content
path: findings/2026-03-22-example.md
type: finding
---
Verify cross-references resolve
Check that the referenced file exists in the other repo:
ls /home/devarno/code/workspace/so1-io/so1-content/findings/2026-03-22-example.md
Verify the push succeeded
git -C /home/devarno/code/workspace/atlas status -sb
# Should show: ## main...origin/main (no "ahead" indicator)
Current Inventory
As of the v2.0 migration:
- 42 learnings in
learnings/ — all have type: learning and canonical cross_ref: arrays
- 37 bidirectional pairs between atlas learnings and so1-content findings
- 5 unpaired learnings (atlas-only content with
cross_ref: [])
How to Extend
Add a new content type to atlas
- Edit
.archive-manifest.yaml — add a new entry to the accepts: array
- Update
CLAUDE.md — add the new type to the frontmatter schema section
- Update
so1-io/CLAUDE.md — add classification rules for the new type
- Commit + push
Add a new repo to the system
- Create
.archive-manifest.yaml in the new repo
- Add entry to
~/.config/opencode/archive-registry.yaml
- Update
CLAUDE.md files in all repos (Archive System Peers tables)
- Commit + push
Change the path template
Edit .archive-manifest.yaml path_template field. Existing files are not moved — only new archives use the new template.
Key Files in This Repo
| File | Purpose |
|---|
.archive-manifest.yaml | Declares accepted types, paths, schemas |
CLAUDE.md | Agent instructions including frontmatter schemas |
learnings/*.md | Business learnings (42 files) |
campaigns/*.md | Marketing campaigns |
docs.json | Mintlify navigation config |
- Archive Command Chain — Full technical runbook in so1-content covering all 5 repos, all 4 command modes, manifest schemas, and troubleshooting
- Orchestration Runbook — Factory Orchestrator workflows that invoke
/archive
Troubleshooting
Push rejected
git pull --rebase && git push
File collision
The system appends -2 to the slug if the computed path already exists.
Cross-ref points to non-existent file
Cross-refs are committed in order (so1-content first, then atlas). If you see a ref to a file that doesn’t exist, check if so1-content has been pushed yet.
Missing type: in frontmatter
All files should have type: learning or type: campaign. If a file is missing it, add the field manually. The manifest’s frontmatter.required list includes type.
Manifest not found
Check that .archive-manifest.yaml exists at the atlas repo root:
cat /home/devarno/code/workspace/atlas/.archive-manifest.yaml
