# cproof-context

Agent-oriented context documentation for the [cproof](https://git.jabber.space/devs/cproof)
project (a fork of Profanity, a terminal-based XMPP client written in C).

This repository is **not** human-onboarding documentation. It is structured for
consumption by AI/agent skills — tables over prose, concrete identifiers over
descriptions, layered files loaded on demand.

## Layout

| Path | Churn | Purpose |
|---|---|---|
| `SKILL.md` | low | Always-loaded entry hint. Points to `INDEX.md`. |
| `INDEX.md` | low | One-page map of every doc with churn label. |
| `architecture/` | low | Stable structural reference: source map, test map, data flow. |
| `patterns/` | medium | Codified conventions: memory, commands, autocomplete, events, etc. |
| `testing/` | medium | How tests are organised, written, and stubbed. |
| `build/` | medium | Local, Docker, and CI build flows. |
| `playbooks/` | medium | Step-by-step recipes for common tasks. |
| `gotchas.md` | append-only | Dated entries: one per known pitfall. |
| `wip/` | high | Branch-specific notes for in-flight features. Deleted on merge. |

See `INDEX.md` for the full file list.

## Consumer

Consumed by an agent skill that operates on the cproof codebase. The skill
should pin this repo to a specific SHA (not a branch) and treat the loaded
files as authoritative for their stated scope.

## Update flow

1. Edits land via PRs against `master`.
2. Drift checks (path / identifier existence in cproof HEAD) run in CI before
   merge — see `architecture/test-map.md` and `build/ci.md` for details once
   wired up.
3. After major cproof refactors, the skill consumer bumps the pinned SHA to a
   commit known to pass drift checks.

## Out of scope

- User-specific agent preferences (language, commit-trailer policy, etc.) —
  belong in agent memory, not here.
- Git history snapshots, changelogs, PR summaries — derivable from `git log` /
  `gh pr`.
- Aspirational guidance — this repo describes cproof as it is, not as it
  should be.

## Baseline and WIP

The stable layers (`architecture/`, `patterns/`, `testing/`, `build/`,
`playbooks/`, `gotchas.md`) describe **cproof on `master`**. They do not
mention symbols, files, or commits that exist only on a feature branch.

In-flight feature branches that materially change the surface (new module,
new commands, new stubs) get a single file under `wip/<branch-slug>.md`. On
merge to `master`, that file is deleted and any surviving content is folded
into the stable layers.

Current WIP: `wip/feat-ai.md` (cproof branch `feat/ai`).

## Status

Layout is being authored on `draft/split-context`. The single
`file-structure.md` (still present on `feat/add-context`) is being decomposed
into the structure above; once the split is complete, `file-structure.md` is
deleted.