Atlas Portal — documentation
Start here.
By question
| You want to | Read |
|---|---|
| Train someone on copywriting | guides/ |
| Understand where this is all going | vision.md |
| Know what this system is and why it's shaped this way | ../ARCHITECTURE.md |
| Understand where AI is used, and where it deliberately isn't | agent-architecture.md |
| Instructions for any agent working here | ../AGENTS.md |
| Know what *your role* does in the system | roles.md |
| Do a specific task, step by step | sop/ |
| Know why something is built the way it is | decisions.md |
| Know what account is where, and what has already bitten us | infrastructure.md |
| Pick up where the last agent or session left off | HANDOVER.md |
| Know what Alex decided, what went wrong, and what is true about clients and tools | knowledge/ |
| Deploy, or stand up a new environment | ../DEPLOY.md |
| Know what breaks, what self-heals, and what pages someone | ../OPERATIONS.md |
The two areas
Creative Studio — the daily tool. Delivery picks an approved angle and generates ad statics. High volume, no judgment required, no AI in the path.
Brand Intelligence — maintenance. Strategists feed in client content, and the system extracts what's verifiable, reconciles it against what's known, and escalates only genuine conflicts. Low volume, judgment-heavy.
They're separate because they have different users, different cadences, and mixing them clutters the tool the delivery team opens every day.
Documentation rules
Because documentation that isn't maintained is worse than none — it becomes confidently wrong.
- Every subsystem ships with its SOP. Not afterwards.
- Say what does not exist. A doc describing a feature that isn't built is the most expensive kind of wrong. Stubs here are explicitly marked *Not built yet*.
- SOPs are written for the person doing the task, in their language, not the system's.
- One source of truth per fact. Link, don't restate. A number copied into two documents will disagree within a month.
- The methodology skills in
../skills/are documentation too — they are what the agents actually follow, so they are the real spec for extraction quality.
Every rule, one line
The table that used to head CLAUDE.md. Full text behind each link.
| Rule | One line | |
|---|---|---|
| Access | One gate in middleware; nothing answers without a credential; fail closed | |
| Guardrails | A creative needs an approved angle and approved copy — enforced in the database, not the UI | |
| Verification | A passing build is not evidence; run ./scripts/qa.sh <host> | |
| Cost | No model in the high-volume path; one scene, many creatives | |
| Higgsfield first | Anything creative — check Higgsfield before building it. We own the argument, not the rendering | |
| Skills | One owner per concept. A new skill isn't done until the skills it displaced defer to it | |
| Taste | Slop is averaging; taste is a rejection function. Generate wide, kill hard, be allowed to refuse | |
| Creative intelligence | Buy competitor evidence — the Ad Library API cannot serve SG. Build the feedback loop. Enforce diversity at the idea | |
| Creative engine | Strategy is 50–60% of performance, execution 30–40%. Judges are pairwise, blind, and excluded when they contradict themselves | |
| Marketing levels | Market → positioning → offer → angle → creative. Name the binding level; you cannot fix at level 1 what is broken at level 3 | |
| Depth | Skill, agent, or ecosystem — decide before building, record when you go thin | |
| Performance | Nothing a human waits on calls a model; build in dependency order | |
| Data safety | 13 tables cascade from clients and the app is superuser — revoke DELETE, ship backups offsite | |
| Credentials | OAuth tokens rotate — persist them, one chain per consumer | |
| Meta read-only | ANALYZE token only. Never pause, never spend — the guarantee is a permission, not a policy | |
| Naming | Each level says what only it can say; the angle code in the ad name is what closes lineage | |
| Agent orchestration | Who holds the plan decides the primitive; routines, not cron; a fan-out needs a cost ceiling | |
| Retrieval | Under ~200k tokens, skip RAG entirely; contextualise chunks; filter by audience *and* subject | |
| Self-improvement | Check in code what is checkable; the outer loop needs outcomes, and ours is blocked on one approval | |
| Video generation | Check Higgsfield first; we own the argument, not the rendering; route the tool so nobody picks it | |
| Interface design | Look it up on refero before styling; the accent must not drive the neutrals; say it once | |
| Design | The look lives in tokens, not pages; two materials, one hue; check /style | |
| Working sessions | One area per session; build the reconciliation before the feature; a number states its scope | |
| Documentation | Ship docs with the change; "Built" and "Live" mean different things | |
| --- | --- | --- |