/genesis

Author

fariazinhu

/genesis              # analyze the current directory
/genesis <path>       # analyze a specific directory
/genesis --force      # regenerate even if .aether/docs already exists

What it does

1. Scans the entire project — configs, entry points, and every source file that fits the context budget (no arbitrary file-count cap). The default budget is sized for large-context models, so a typical project goes in whole; anything it does have to leave out is listed explicitly, never dropped silently.
2. An AI planning pass decides which docs actually make sense for this project. Always generated: the human guides (getting-started, onboarding), the architecture set (system-overview, folder-structure, tech-stack), and AI_CONTEXT.md. Everything else (contributing, coding-standards, modules, api, business, diagrams, glossary) is only included with real evidence — a frontend or devops project won't get api/endpoints.md just because it's on the list.
3. The AI can also propose a handful of custom docs beyond the fixed catalog when something project-specific deserves its own page (e.g. an unusual build pipeline).
4. Docs are written to .aether/docs/, generated concurrently with retry + backoff on failures, plus a docs/README.md index that links everything.

Each doc is generated from a single shared project context built once before generation starts. If the whole project fits the model's budget, it's sent as real code; when it doesn't, Aether distills the entire project once into factual notes and reuses them for every doc — so nothing is dropped, the expensive pass runs a single time, and all docs stay consistent with each other. Requests stream under the hood with an idle timeout, so a slow model that keeps responding is never cut off mid-answer.

If .aether/docs/ already exists, /genesis won't regenerate it by default — it'll point you to /sync instead. Use --force to fully regenerate anyway.

When generation finishes, genesis offers to build docs.html — a free, browsable single-file viewer of the docs (sidebar, search, rendered diagrams). It's generated locally from the Markdown, so saying yes costs nothing.

Tuning the scan budget

The defaults fit most projects into a large-context model without omitting anything. You can open them up further for a very large repo, or tighten them for a small local model, via environment variables:

Two audiences, two contracts

Genesis writes for both people and AI, and they don't get the same treatment:

• Human guides (guides/) lead with the why and explain how the pieces connect. They read like onboarding, not an index. If your repo already has author-written context (a README, CONTEXT.md, …), they lean on it for intent — but you don't have to write anything; they're generated from the code either way.
• AI & architecture docs (AI_CONTEXT.md, architecture/, etc.) stay strict and traceable — every claim maps to a file, so an assistant can trust them without hallucinating.

Both share the same accuracy floor: nothing invented, and a planned feature is never described as already built.

Output structure

.aether/docs/
├── README.md                (always — index of everything below)
├── guides/
│   ├── getting-started.md   (always — install & run, for humans)
│   ├── onboarding.md        (always — mental model & the why)
│   └── contributing.md      (if there's a real contribution process)
├── architecture/
│   ├── system-overview.md   (always)
│   ├── folder-structure.md  (always)
│   ├── tech-stack.md        (always)
│   └── coding-standards.md  (if applicable)
├── modules/overview.md      (if applicable)
├── api/endpoints.md         (only with an actual API/CLI to document)
├── business/rules.md        (if applicable)
├── diagrams/system.md       (if applicable)
├── AI_CONTEXT.md            (always)
├── glossary.md              (if applicable)
└── ...                      (+ custom docs the AI proposes for this project)