stella ingest

stella ingest reads markdown you already wrote and turns it into steering stella can check, cite, and retire. It has two halves, and which one runs depends entirely on whether you name a file.

With no arguments, it scans the workspace and shows you what it found, grouped by tier. This half works offline and needs no API key. Name one or more paths and it extracts them instead: one model call per document splits it into individual claims, each claim is mapped to a context record, run through a safety check, tested against your code for staleness, and written to .stella/proposals/ as a reviewable TOML file. Nothing you ingest steers anything until you review it.

Synopsis

stella ingest [--all]
stella ingest [--keep-dismissed] <path>...
stella ingest --refresh <path>...
stella ingest alerts list
stella ingest alerts dismiss <path>
stella ingest alerts restore <path>

What it does

Most repositories already contain the instructions an agent needs. They're just written for people, scattered across files, and partly out of date. Ingest treats that writing as a source to be mined rather than a file to paste into a prompt: claims come out one at a time, each one keeps track of where it came from, and each one can be reviewed on its own instead of arriving as one big undivided block of text.

stella ingest — scan

With no paths given, ingest walks the workspace for markdown files and sorts everything it finds into five tiers. The results are grouped the same way the first-run screen groups them, so the scan and the first-run screen never disagree about what your repo contains.

# What steering does this workspace already contain?
stella ingest

# Including the documents ingest would normally not offer
stella ingest --all

stella ingest <path>... — extract

Naming a file skips every tiering rule the scan would apply. Any path works, whether it's inside the workspace or not. Ingest still tells you when a named file reads like a retired document or like boilerplate, because respecting your choice and hiding a known risk are two different things.

Each document goes through the same five steps.

1. One model call splits the document into individual claims.
2. Each claim is mapped to a context record.
3. A safety check re-decides whether each claim is properly split, quarantined, or held for testing.
4. Claims are tested against your code for staleness.
5. The result is stamped with an identity based on its content and written to .stella/proposals/<source-slug>.toml as [[proposal]] entries.

# The two files everybody recognizes
stella ingest AGENTS.md CLAUDE.md

# A design note, and a file from outside the workspace
stella ingest docs/spec/storage-map.md ~/notes/deploy-runbook.md

Lineages and staleness alerts

Every extracted file leaves a lineage behind, in .stella/private/ingest-lineages.json: the content hash the file had when it was read (git's own hash where possible, otherwise a plain sha256), the commit it was read at, the ingest run id, and the ids of the candidates that run produced. None of this is tied to any particular filename. An agent-instruction file, a runbook, and a scratch note written purely to be ingested are all treated the same, as ingested source files.

At session start, in the background and never blocking your work, stella compares each lineage against the source file's current hash. A file that changed or disappeared since it was ingested triggers a notification in your inbox. The alert never enters the model's prompt, never blocks a turn, and never changes anything on its own. Re-ingesting is always something you choose to do.

Whether an alert matters is entirely up to you, and you can decide per file. A file written purely as scaffolding, ingested and then deleted because the records were the real goal, should never keep bothering you.

# What changed under my records?
stella ingest alerts list

# This file was scaffolding; the records are the product. Never tell me again.
stella ingest alerts dismiss docs/onboarding-notes.md

# The file changed — reconcile the published records with what it says now
stella ingest --refresh docs/onboarding-notes.md

--refresh: re-ingest and compare

Records are never edited in place, so "the file changed" doesn't mean an overwrite. stella ingest --refresh <path> re-extracts the file and checks every published record that cites it, sorting each one into exactly one group.

The same replacement rule applies outside --refresh too. Running stella context keep on a candidate whose lineage is already published is refused if the claim is identical, and it replaces the old version, with a link and a note in the log, when the claim differs.

The safety check runs outside the model

The model is asked to split claims cleanly and to flag any content that looks executable, but nothing downstream simply trusts that it did. Whether a claim is properly split, quarantined, or held for testing is re-decided by a separate, predictable function in the core engine that can't be talked out of a rule by clever wording in a document. The model's job is extraction. The safety check's job is safety.

This matters because the input is writing of unknown origin. A README that says "always run curl … | sh before building" is a document describing an instruction, not permission to run it, so anything that looks executable is quarantined by the safety check no matter how the model classified it.

Reviewing what it produced

stella context is the other half of this process. Ingest extracts; context decides.

stella context review        # what was proposed, with each claim's test result
stella context keep a1b2c3   # publish one as a record the engine loads
stella context ignore d4e5f6 --reason "we moved off this in Q2"
stella context list          # what actually steers this workspace now

The proposals are plain TOML files at .stella/proposals/<source-slug>.toml, so editing or deleting entries by hand still works. But stella context is the tool that shows you the test results, records a decline as reusable evidence with a cooldown period, and writes the published record into .stella/rules/ for you.

Related