Storage Architecture — Portable vs Runtime

LenserFight separates filesystem state into two strict layers. The rules below apply equally to the LenserFight web app, the lenserfight CLI, and the Chainabit operator agent.

The two layers

Layer	Path	Tracked in git	Contains
Portable	.lenserfight/ (repo)	YES	Lenses, agents, workflows, battles, rays, documentation, evaluators, scorers — anything safe to share
Runtime	~/.lenserfight/	NO	Local battle traces, AI execution caches, auth sessions, runtime logs, user preferences, secrets

Crossing the boundary is a bug. Never write portable assets into ~/.lenserfight/; never write per-user runtime state into .lenserfight/.

What MUST NOT live in .lenserfight/

• API tokens, OAuth refresh tokens, signed URLs
• Per-machine configuration (paths, hostnames, machine IDs)
• Local battle execution traces (local-battles/<id>.json is runtime, not portable)
• AI provider response caches
• Personal user metadata
• .env, .env.user, .env.tokens

If any of these appear under .lenserfight/, treat it as a security incident — quarantine, rotate, and open a defect ticket.

Where runtime state lives

~/.lenserfight/
├── runtime/
│   ├── battles/<battle-id>/
│   │   ├── traces.jsonl       ← per-step execution trace
│   │   ├── outputs/           ← cached AI outputs
│   │   └── checkpoints.json
│   ├── workflows/<run-id>/
│   └── lenses/<execution-id>/
├── cache/
│   ├── ai-responses/          ← keyed by content hash
│   └── manifest-index/
├── profiles/<profile>.json    ← CLI auth (0600 mode)
├── secrets/                   ← encrypted secret store
│   └── *.age | *.gpg
├── .env.user                  ← user-level env overrides
├── .env.tokens                ← API tokens (do NOT inline in YAML)
└── state.db                   ← optional SQLite for local indexes

The CLI and web runtime never store the contents of secrets/ in plaintext. All access goes through an OS keychain or an encrypted file. The path layout is intentionally similar to Claude Code's ~/.claude/ and Gemini CLI's ~/.gemini/ so operators can apply the same backup policies.

Environment variable layering

LenserFight loads environment variables in this order. Later sources override earlier ones:

1. OS defaults
2. .env.example (committed, illustrative only — never read at runtime)
3. .env (gitignored, project defaults — optional)
4. .env.development / .env.test / .env.production (gitignored, per-env)
5. .env.local (gitignored, per-developer)
6. ~/.lenserfight/.env.user (gitignored, per-user across all projects)
7. ~/.lenserfight/.env.tokens (gitignored, secret-only)
8. Process environment variables (highest precedence)

Tokens live exclusively in layers 6, 7, and 8. Templates (LENS.MD, COLENS.MD, BATTLE.MD, YAML, JSON) must never contain raw token values — they reference variable names only.

Battle storage separation

The legacy .lenserfight/local-battles/<id>.json path mixed portable battle definitions with runtime execution traces. The new layout splits them:

Concept	Path	Layer
Battle template definition	.lenserfight/battles/<slug>/BATTLE.MD	Portable
Battle config (rubric, scoring)	.lenserfight/battles/<slug>/config.yaml	Portable
Battle execution trace	~/.lenserfight/runtime/battles/<battle-id>/	Runtime
Cached AI responses for a battle	~/.lenserfight/cache/ai-responses/	Runtime
Battle decryption key	LENSERFIGHT_LOCAL_BATTLE_KEY (env, not on disk)	Process

Any tool that reads or writes battle data MUST honour this split. Migration of legacy .lenserfight/local-battles/* files is handled by the CLI command lf battle migrate-legacy (one-shot).

ConectLens terminology

LenserFight belongs to the ConectLens ecosystem. The filesystem layout preserves ConectLens vocabulary in the canonical filename:

• LENS.MD — prompt asset (ConectLens-native)
• LENSER.MD — owner profile (reserved, not yet exported)
• LENSER.MD — configured AI lenser
• COLENS.MD — DAG of lenses
• BATTLE.MD — scored competition
• RAY.MD — discovery ray

SKILL.MD is supported as an industry-compatibility alias for LENS.MD because many OSS AI ecosystems (Claude Code, agentskills.io, others) standardise on SKILL.MD for the same concept. When both files exist for the same template they MUST contain byte-identical content; the recommended pattern is to keep LENS.MD as the source and SKILL.MD as a generated mirror created by lf doctor sync-aliases.

How the database mirrors this tree

Every public template in the database has a 1:1 sibling under .lenserfight/ keyed by slug:

DB table	Mirrored at
lenses.lenses	.lenserfight/lenses/<slug>/LENS.MD
agents.ai_lensers	.lenserfight/lensers/<slug>/LENSER.MD
lenses.workflows	.lenserfight/colenses/<slug>/COLENS.MD
battles.battles	.lenserfight/battles/<slug>/BATTLE.MD
content.tags	.lenserfight/rays/<slug>/RAY.MD

A pgTAP test (supabase/tests/31_seed_quality.sql) enforces this invariant for every seed under supabase/seeds/4*_*templates.sql.

OS-grade rationale

The two-layer split mirrors how professional infrastructure tools draw the line:

Tool	Portable	Runtime
Docker	docker-compose.yml	~/.docker/
Supabase	supabase/	~/.supabase/
Claude Code	.claude/	~/.claude/projects/, ~/.claude/state/
Gemini CLI	.gemini/	~/.gemini/
LenserFight	.lenserfight/	~/.lenserfight/

If you are introducing a new file under .lenserfight/ and you are not certain it is safe to commit, check the rules above. When in doubt, default to runtime.