AI documentation polish

When you encounter a Kotlin declaration without KDoc, Field can ask a fast model for a short description and show it in the completion popup. Field keeps these drafts in a cache, where they can be reviewed and turned into KDoc in the source. Once there, the descriptions also reach the reference pages. The work happens in the same documentation revision pass that handles your notes on the docs.

Polishing the drafts

The KDoc drafts card on /welcome counts the drafts for declarations under src/, and how many files they are spread over:

Review in docs pass opens /docs-pass.html. There, Import completion KDoc drafts adds each draft as a note on its declaration's line, with the tag @kdoc-draft. Once the import finishes, the queue counts the drafts among its open notes:

The terminal equivalent of the import is:

:::static
uv run python tools/docs_notes.py import-drafts

From there, a draft is handled like any other note. Drain the queue runs one agent per Kotlin file; enter @kdoc-draft in the tags box to work only on drafts. The agent receives the draft, the declaration, the writing rules and relevant notes, including any note you left on the same KDoc. Your note takes precedence.

The agent checks the draft against the declaration and its callers, then writes or corrects the KDoc. If the declaration needs none, it resolves the draft without adding text. If it cannot work out what the code does, it asks under Questions for you. You can then review the diff and finish the pass.

Only declarations in this repository are drafted, in any source set under src/, including src/personal. A declaration from a dependency's sources jar is never sent to the model and never imported.

The draft cache

The cache is <checkout>/.field/filestore/generated_completion_docs.json: one per checkout, seeded on first use from the machine-global ~/.afield/filestore, and relocated by AFIELD_FILESTORE_DIR or -Dafield.filestore.dir. Each record carries the declaration's name, path, line and source hash alongside the draft, the model that wrote it, and when.

Editing a declaration retires its draft, so a draft always describes the code as it is. Drafts the pass declined are listed in generated_completion_docs.declined.json beside the cache.