jobs: Instructions file for Codex

IMPORTANT: As you implement features, keep the documentation up to date; update README.md only when a doc file is added or new users must know.

Overview

You are working on Jobs, a hierarchical task manager for the CLI, backed by an event store in SQLite.

Documentation

• docs/content/docs/ — the published documentation site (Hugo); make docs serves it locally. reference/ is the full CLI reference — the fastest way to learn what a command does.
• README.md — what Jobs is and a quick start, written for humans
• DESIGN.md — the dashboard's design system: tokens, type scale, component specs
• project/ — dated design documents and agent-feedback reports; project/gotchas.md holds project traps and rule feedback
• Makefile — build, install, test, test-js, and the docs targets
• scripts/ — re-runnable tooling (screenshots, snapshot replay, getting-started verification)

Architecture

internal/job is the product — the SQLite event store, the plan grammar, and the rendering. cmd/job is a thin cobra CLI over it, and internal/web is a server-rendered dashboard over the same core.

• Schema changes are numbered migrations in internal/migrations/. They are applied when the database is opened, so any job invocation migrates — there is no server to restart.
• DESIGN.md is the design system the web rules below defer to, authoritative for everything under internal/web/ — including its desktop-first density target, which outranks the web rules' mobile-first default. The dashboard is localhost-only and read-only, so the rule about public-page <head> metadata does not apply here.
• The dashboard's JS is mostly plain progressive-enhancement modules in internal/web/assets/js/, not custom elements; only peek-sheet and live-region are registered, and neither uses a shadow root. The web rules' one-element-per-file-with-a-shadow-root convention governs new components — don't retrofit the existing scripts to it as a side quest.
• This repo builds job. The job on your PATH and the ./job at the repo root are both stale until make install / make build, so a CLI change you just wrote is not exercised by running job until you rebuild.
• Never name a client or a client's repo in anything committed — code, comments, project/ docs, commit messages, and job titles, descriptions, notes and criteria (the .jobs/log is committed too). Say "a client repo" or "a client store". Real stores from other repos are fine to measure against; their names stay out of this one.