Skip to main content

​
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

RepoOrgWhat It StoresAudience
atlas (this repo)devarno-cloudBusiness learnings + marketing campaignsBusiness / Marketing
so1-contentso1-ioTechnical findings (bugs, patterns, decisions)Engineering
veritasso1-ioReusable prompts (quarantined before promotion)Engineering
arieltraceo-aiFrozen baselines + specs (MkDocs site)Engineering
traceo-mcp-servertraceo-aiMCP 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…TypeGoes to
A bug fix or technical decisionfinding + learning (paired)so1-content + atlas
A business insightlearningatlas
A marketing assetcampaignatlas
A reusable promptpromptveritas
An architecture freezebaselineariel
A spec changespecariel

​
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
This creates a bidirectional web — if a learning references a finding, that finding also references the learning.

​
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
Expected frontmatter: 
---
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

  1. Edit .archive-manifest.yaml — add a new entry to the accepts: array
  2. Update CLAUDE.md — add the new type to the frontmatter schema section
  3. Update so1-io/CLAUDE.md — add classification rules for the new type
  4. Commit + push

​
Add a new repo to the system

  1. Create .archive-manifest.yaml in the new repo
  2. Add entry to ~/.config/opencode/archive-registry.yaml
  3. Update CLAUDE.md files in all repos (Archive System Peers tables)
  4. 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

FilePurpose
.archive-manifest.yamlDeclares accepted types, paths, schemas
CLAUDE.mdAgent instructions including frontmatter schemas
learnings/*.mdBusiness learnings (42 files)
campaigns/*.mdMarketing campaigns
docs.jsonMintlify 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
If missing, it needs to be recreated — see the manifest schema in the Archive Command Chain runbook.