ELIC (Explain Like I Code) is a TypeScript-first workspace for task-scoped code Explanations generated by AI agents and presented on local surfaces.

ELIC exists because chat is a weak presentation layer for understanding code. When a developer asks why a bug happened, how a PR works, or how a library architecture is changing, the answer should be navigable, grounded in source evidence, and adjustable by Detail Level. Most Explanations are expected to be one-off and disposable; saved Explanations are optional.

The transport between an agent and a Presentation Surface is a strict JSON Explanation. An Explanation organizes Topics, optional Flows, ordered Steps, and grounded Anchors. Explanation Sessions are presented on Active Surfaces: terminal first and OpenCode next.

ELIC is not trying to be a wiki, docs site, living documentation platform, or durable onboarding tour system. It is a local presentation format for tailored AI answers about code.

• CONTEXT.md defines the project language.
• docs/explanation-v1-contract.md defines the draft v1 JSON artifact, authoring, validation, hydration, and Presentation Surface contract.
• Saved authored Explanations live under .elic/explanations/*.explanation.json. One-off Explanations may use any explicit path and do not need to be kept in the repo.
• Neovim is preserved only as a legacy adapter direction and does not define the v1 Explanation contract.

• packages/schema owns the v1 Explanation contract and Effect Schema validation/parsing helpers.
• packages/core owns Explanation loading and core artifact helpers. Presentation Surfaces should not force alternate artifact shapes back into core.
• packages/tui contains the terminal visual direction. The UI vibe is retained; its current data model is not authoritative.
• packages/cli provides the command surface and should grow elic validation, hydration, strip, and view workflows from the v1 contract.
• packages/tourguide.nvim is historical legacy adapter code.
• skills/elic contains the JSON-authoring skill contract for agents.

Current scaffold commands:

bun install
bun run build
bun run test

Target v1 one-off flow:

elic validate --hydrate <path>/<name>.explanation.json
elic view <path>/<name>.explanation.json

Target v1 saved flow:

elic validate --hydrate .elic/explanations/<name>.explanation.json
elic validate --lint .elic/explanations/<name>.explanation.json
elic view .elic/explanations/<name>.explanation.json

This is an early scaffold in transition. Existing schema, core, CLI, fixtures, and authoring examples may not match the v1 contract yet. Treat docs/explanation-v1-contract.md and CONTEXT.md as the source of truth while the implementation is rebuilt.