Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
128 commits
Select commit Hold shift + click to select a range
78b8e1c
docs: the README leads with a recipe that keeps changing, and its pic…
BattermanZ Oct 12, 2026
58bdc7b
docs: the README keeps its six pictures, with the History and a cooki…
BattermanZ Oct 12, 2026
cc94316
Merge pull request #248 from BatterWorks/docs/readme-leads-with-history
BattermanZ Oct 12, 2026
144988c
fix: the History draws every line out of the dot it started from
BattermanZ Oct 12, 2026
88156e6
Merge pull request #252 from BatterWorks/fix/250-history-translation-…
BattermanZ Oct 12, 2026
6a264c2
feat: the History shows a Version's cookings as two badges at most
BattermanZ Oct 13, 2026
a141827
Merge pull request #254 from BatterWorks/feature/249-history-cooking-…
BattermanZ Oct 13, 2026
a03a203
fix: branch_point and divergence refuse a Translation instead of call…
BattermanZ Oct 13, 2026
b670734
Merge pull request #255 from BatterWorks/fix/251-translation-branch-p…
BattermanZ Oct 13, 2026
660ac00
docs: the README's History picture shows the History as it is drawn now
BattermanZ Oct 13, 2026
61d9fec
Merge pull request #256 from BatterWorks/docs/253-readme-history-picture
BattermanZ Oct 13, 2026
28c5bc3
docs: an agent beside Kamosu reads what Kamosu cannot (ADR 0048)
BattermanZ Oct 13, 2026
dbf3a6f
Merge pull request #257 from BatterWorks/docs/agent-import-runner
BattermanZ Oct 13, 2026
3ebd6b2
docs: rewrite ADR 0048 around a key for each Job
BattermanZ Oct 13, 2026
6da3cd6
Merge pull request #259 from BatterWorks/docs/adr-0048-rewrite
BattermanZ Oct 13, 2026
b4ca402
feat: an Operator mints a Runner Key, which can ask for work and noth…
BattermanZ Oct 13, 2026
e313a90
Merge pull request #282 from BatterWorks/feature/260-runner-key
BattermanZ Oct 13, 2026
35c8fec
feat: a link Kamosu cannot read lands bare and a Job waits for an agent
BattermanZ Oct 13, 2026
555ac17
Merge pull request #283 from BatterWorks/feature/261-agent-job-waits
BattermanZ Oct 13, 2026
279e26e
feat: a Runner takes a waiting Job and reports how it ended
BattermanZ Oct 13, 2026
eaa1f68
Merge pull request #284 from BatterWorks/feature/262-runner-takes-and…
BattermanZ Oct 13, 2026
960a3d3
feat: the Job Key reads the library as the Person who asked
BattermanZ Oct 13, 2026
85d27a7
Merge pull request #285 from BatterWorks/feature/263-job-key-reads
BattermanZ Oct 13, 2026
2d9502b
feat: the Job Key writes the one recipe of its Job
BattermanZ Oct 13, 2026
a08809e
Merge pull request #286 from BatterWorks/feature/264-job-key-writes
BattermanZ Oct 13, 2026
4312de6
feat: a Job leaves at most one new Version
BattermanZ Oct 13, 2026
2230cbf
Merge pull request #287 from BatterWorks/feature/265-job-leaves-one-v…
BattermanZ Oct 13, 2026
e567aa8
feat: a Runner keeps its hold by renewing it
BattermanZ Oct 13, 2026
b374480
Merge pull request #288 from BatterWorks/feature/266-runner-renews-it…
BattermanZ Oct 13, 2026
fc8c08b
feat: an agent's Job is cancelled while it is being worked
BattermanZ Oct 14, 2026
f34d559
Merge pull request #289 from BatterWorks/feature/267-cancel-an-agents…
BattermanZ Oct 14, 2026
1ecd95c
feat: a Co-author reads an agent's Job, and the recipe names it
BattermanZ Oct 14, 2026
cf44041
Merge pull request #290 from BatterWorks/feature/268-co-author-reads-…
BattermanZ Oct 14, 2026
19e5878
feat: pasted text, a PDF or a picture is handed to the agent
BattermanZ Oct 14, 2026
4819686
Merge pull request #295 from BatterWorks/feature/269-hand-an-original…
BattermanZ Oct 14, 2026
4b992bc
fix: opening a Bundle holds at most a fixed total in memory
BattermanZ Oct 14, 2026
18ffaf5
Merge pull request #297 from BatterWorks/fix/296-bundle-total-cap
BattermanZ Oct 14, 2026
5ea6de1
feat: an Original is deleted 30 days after its Job ended
BattermanZ Oct 14, 2026
c0c7539
Merge pull request #298 from BatterWorks/feature/270-originals-delete…
BattermanZ Oct 14, 2026
3b2e3af
feat: the same link or file handed over twice is matched
BattermanZ Oct 14, 2026
19c09fc
Merge pull request #299 from BatterWorks/feature/271-same-handover-ma…
BattermanZ Oct 14, 2026
636605e
feat: a Co-author asks for a recipe to be read again from its link
BattermanZ Oct 14, 2026
6037267
Merge pull request #300 from BatterWorks/feature/272-read-again-from-…
BattermanZ Oct 14, 2026
096e669
feat: a link with no recipe data is read from its text when there is …
BattermanZ Oct 15, 2026
eae8d5b
Merge pull request #304 from BatterWorks/feature/301-read-link-page-text
BattermanZ Oct 15, 2026
0c3190b
feat: a recipe that came from a file is read again from its Original
BattermanZ Oct 15, 2026
c52b0da
Merge pull request #305 from BatterWorks/feature/273-read-again-from-…
BattermanZ Oct 15, 2026
58ac640
feat: the Runner, Kamosu started in another mode beside an agent
BattermanZ Oct 15, 2026
38ecdd5
Merge pull request #306 from BatterWorks/feature/274-the-runner
BattermanZ Oct 15, 2026
7b994c0
feat: Runner Keys on the Operator screen
BattermanZ Oct 15, 2026
2dc461e
Merge pull request #307 from BatterWorks/feature/275-runner-keys-in-s…
BattermanZ Oct 15, 2026
d0d5b53
feat: the Import Report says what an agent did
BattermanZ Oct 15, 2026
e79441f
Merge pull request #309 from BatterWorks/feature/276-import-report-agent
BattermanZ Oct 15, 2026
1b21cd8
feat: an agent's Job says whether it waits or is being read
BattermanZ Oct 15, 2026
656522b
Merge pull request #310 from BatterWorks/feature/277-waiting-and-worked
BattermanZ Oct 15, 2026
f4d10b2
feat: a photo of a page, and pasted text and PDFs, go to Kamosu's AI …
BattermanZ Oct 15, 2026
cef4551
Merge pull request #311 from BatterWorks/feature/278-picture-to-agent
BattermanZ Oct 15, 2026
a689bf1
feat: a recipe's page asks Kamosu's AI agent to read it again, once
BattermanZ Oct 15, 2026
613a5fb
Merge pull request #312 from BatterWorks/feature/279-read-again
BattermanZ Oct 15, 2026
0e2598f
docs: the Runner's setup guide, a README section and a Docker Hub line
BattermanZ Oct 15, 2026
209b8c4
Merge pull request #313 from BatterWorks/docs/280-runner-guide
BattermanZ Oct 15, 2026
8bc6cfd
feat: an Operator can look after any Cookbook, one call at a time
BattermanZ Oct 15, 2026
84e954d
Merge pull request #314 from BatterWorks/feature/302-operator-reach
BattermanZ Oct 15, 2026
9c4d911
feat: the Runner beside opencode, in an image built from the repository
BattermanZ Oct 15, 2026
acb689b
Merge pull request #316 from BatterWorks/feature/315-agent-container
BattermanZ Oct 15, 2026
765fefe
feat: one key setting for any provider in the Runner image
BattermanZ Oct 16, 2026
599fa71
Merge pull request #319 from BatterWorks/feature/318-agent-key
BattermanZ Oct 16, 2026
4411259
feat: the agent in a container of its own, the Runner in Kamosu's image
BattermanZ Oct 16, 2026
516e87d
Merge pull request #320 from BatterWorks/feature/317-runner-without-root
BattermanZ Oct 16, 2026
499e59b
feat: an agent's Job measured, its cost logged, its instructions corr…
BattermanZ Oct 16, 2026
716794d
Merge pull request #322 from BatterWorks/feature/281-live-acceptance
BattermanZ Oct 16, 2026
84998d3
fix: a link's Import Report is titled for a link
BattermanZ Oct 16, 2026
ea24827
Merge pull request #323 from BatterWorks/fix/308-web-link-report-title
BattermanZ Oct 16, 2026
0a1cfed
docs: the agent's answer key, written before the runs
BattermanZ Oct 16, 2026
a65b3ce
feat: the agent's instructions tested on sources that go wrong
BattermanZ Oct 16, 2026
7bb0cc2
Merge pull request #327 from BatterWorks/feature/324-agent-answer-key
BattermanZ Oct 16, 2026
069983d
docs: the agent's cost and reading measured on six model settings
BattermanZ Oct 16, 2026
a569f7e
Merge pull request #330 from BatterWorks/docs/325-agent-cost-by-model
BattermanZ Oct 16, 2026
da90ee3
docs: the Runner guide says what the model measurements found
BattermanZ Oct 16, 2026
2a99140
Merge pull request #331 from BatterWorks/docs/325-runner-guide-haiku-…
BattermanZ Oct 16, 2026
11e368e
fix: the phone's kept library survives a proxy error, an opened recip…
BattermanZ Oct 16, 2026
d1ed576
Merge pull request #332 from BatterWorks/fix/291-offline-library
BattermanZ Oct 16, 2026
916e048
fix: one Bundle import makes a colliding Food once, however many Vers…
BattermanZ Oct 16, 2026
0e310c8
Merge pull request #333 from BatterWorks/fix/292-one-food-per-import
BattermanZ Oct 16, 2026
dba8dd2
fix: a row dragged over a taller one settles where the finger is
BattermanZ Oct 17, 2026
0c824c4
Merge pull request #334 from BatterWorks/fix/293-drag-settles
BattermanZ Oct 17, 2026
d80c414
fix: a Step that adds an ingredient after "until" links it again
BattermanZ Oct 17, 2026
63a2c04
Merge pull request #335 from BatterWorks/fix/294-until-span
BattermanZ Oct 17, 2026
d782612
fix: a reworded Step no longer pairs across another and moves up the …
BattermanZ Oct 17, 2026
cb185f7
Merge pull request #336 from BatterWorks/fix/303-pairing-order
BattermanZ Oct 17, 2026
b25d8cf
fix: a bare recipe takes the Language of the text that first fills it
BattermanZ Oct 17, 2026
9a7dac6
Merge pull request #338 from BatterWorks/fix/321-bare-landing-language
BattermanZ Oct 17, 2026
b72d882
fix: a lone c or # after an amount reads as a cup or a pound
BattermanZ Oct 17, 2026
a3d3f84
Merge pull request #339 from BatterWorks/fix/326-lone-c-and-hash
BattermanZ Oct 17, 2026
3654148
fix: a Version a Bundle carried is no longer being shaped
BattermanZ Oct 17, 2026
5357634
Merge pull request #340 from BatterWorks/fix/328-export-closes-shaping
BattermanZ Oct 17, 2026
19983c4
fix: an unchanged "Start my own copy" says no copy was made
BattermanZ Oct 17, 2026
8536543
Merge pull request #341 from BatterWorks/fix/329-unchanged-copy-says-why
BattermanZ Oct 17, 2026
1541388
fix: a line moved without rewording keeps each page's own order
BattermanZ Oct 17, 2026
750586f
Merge pull request #342 from BatterWorks/fix/337-moved-line-keeps-its…
BattermanZ Oct 17, 2026
4a5d94b
feat: every release publishes the agent image
BattermanZ Oct 17, 2026
656c497
Merge pull request #346 from BatterWorks/feature/345-publish-agent-image
BattermanZ Oct 17, 2026
bd3ecfc
fix: the MCP door lists an Access Key none of the tools it refuses one
BattermanZ Oct 17, 2026
5872483
Merge pull request #350 from BatterWorks/fix/347-access-key-tools
BattermanZ Oct 17, 2026
02d9dec
feat: a video goes straight to the AI agent from the + list
BattermanZ Oct 17, 2026
df42f10
Merge pull request #351 from BatterWorks/feature/349-video-row
BattermanZ Oct 17, 2026
7dc8787
feat: the Runner takes its address and agent socket from the environment
BattermanZ Oct 17, 2026
e199ec7
Merge pull request #352 from BatterWorks/feature/348-runner-env
BattermanZ Oct 17, 2026
ac957eb
feat: an Operator writes House Notes for the agent inside Kamosu
BattermanZ Oct 18, 2026
f6a5ac1
Merge pull request #359 from BatterWorks/feature/344-agent-instructions
BattermanZ Oct 18, 2026
5080e2a
fix: three shapes of Ingredient Line read with a Food
BattermanZ Oct 18, 2026
c4b5d57
Merge pull request #360 from BatterWorks/fix/353-three-line-shapes
BattermanZ Oct 18, 2026
3d3e77d
feat: put an older Version back, or start a variation from it
BattermanZ Oct 18, 2026
b159eee
Merge pull request #361 from BatterWorks/feature/354-older-version-acts
BattermanZ Oct 18, 2026
6adcc01
fix: a line that only moved keeps its Reading on save
BattermanZ Oct 18, 2026
e8b6ed0
Merge pull request #362 from BatterWorks/fix/355-moved-line-keeps-rea…
BattermanZ Oct 18, 2026
7950203
feat: a Translation's line takes the Food of the line it renders
BattermanZ Oct 18, 2026
84cd28a
Merge pull request #363 from BatterWorks/feature/356-translation-take…
BattermanZ Oct 18, 2026
7ac228c
fix: start_translation's listing carries every field meaning again
BattermanZ Oct 18, 2026
4b50430
fix: a Step naming the dish by its title links no ingredient
BattermanZ Oct 18, 2026
77a8123
fix: the dish rule compares accents and runs after the longest mentio…
BattermanZ Oct 18, 2026
d4376d6
Merge pull request #364 from BatterWorks/fix/357-dish-word-links-nothing
BattermanZ Oct 18, 2026
0ef6280
feat: a save names the Foods it created
BattermanZ Oct 18, 2026
cbe5d84
Merge pull request #365 from BatterWorks/feature/358-save-names-foods…
BattermanZ Oct 18, 2026
149b29b
docs: prepare the v0.3.0 release
BattermanZ Oct 18, 2026
ed7b65d
docs: bring the v0.3.0 release checklist level
BattermanZ Oct 18, 2026
59de466
docs: the changelog names the rustls fix
BattermanZ Oct 18, 2026
819c7d9
Merge pull request #366 from BatterWorks/docs/release-v0.3.0
BattermanZ Oct 18, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 73 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -180,6 +180,10 @@ just dev-status # each half running? since when? build-cache size
just dev-logs # follow .dev/kamosu.log and .dev/vite.log together
just dev-stop # stops both process groups
just docker-build && just docker-run # the one-mount-one-port install, as a stranger runs it
just agent-image # Kamosu's image from this tree, for the Runner, then the agent's image (#315, #317)
just runner-start # both beside the dev instance, settings from ~/.config/kamosu-runner.env
just runner-logs # follow the Runner and its agent
just runner-stop # stop both; a Job the Runner held waits again once the hold lapses
```

**Looking at the dev instance has recipes of its own** (#216), so no ticket
Expand Down Expand Up @@ -229,6 +233,10 @@ beside a running Kamosu, and reads `/proc/self/fdinfo` (#130, #215). The
SQLite Kamosu bundles hides the fault that test looks for, and an older one
does not.

**It needs `python3` on the path too.** The Runner's tests start the real
program as a Runner, and its agent command there is a short Python stand-in
that writes a recipe with the Job Key it was handed (#274).

`dev-clean` deletes `target/` to reclaim build cache; the next build is a full
rebuild. Dev state lives in gitignored `.dev/`.

Expand Down Expand Up @@ -352,14 +360,31 @@ src/core/ the Core, one file per area, all adding to one `Core`:
whose recipes (ADR 0041)
cookbooks.rs Cookbooks: who may change a recipe, joining and
separating two, variations, and the may-see and
may-change checks every area calls (ADR 0041, #131)
may-change checks every area calls, an Operator
acting as one on a call that says `as_operator`
among them (ADR 0041, ADR 0049, #131, #302)
recipes.rs creating, saving, reading a recipe; threads and divergence;
unfolding components; `parse_recipe_content`
tags.rs Tags, and putting one on a recipe
related.rs Related Recipes (#105)
runners.rs Runner Keys, a Runner taking a Job, renewing its hold and
reporting how it ended, the Job Key that comes with one
and the one recipe its writes are held to, who reads an
agent's Job, whether the instance has a Runner, and the
House Notes every Job carries to its agent (ADR
0048, #260, #262, #263, #264, #266, #268, #344)
shelves.rs the home shelves, and the shelf entry every list shows
translation.rs translation and a Branch's Language
reading_again.rs a Co-author asking for an agent to read a recipe again
from its kept Original, a file handed over again, or
its Source's link, and whether one can (#272, #273)
readings.rs Ingredient Lines, Readings, Foods and Food merges
originals.rs pasted text, a PDF or a picture handed to an agent,
kept under originals/ for its Job's Job Key alone and
in no Backup, and deleted 30 days after its Job ended.
The same file handed over again is known by its
contents, and a Job that failed on one is asked
again from it (#269, #270, #271, #273)
cooking.rs Attempts and promotion
keeping_photographs.rs
storing, reading and sweeping Photographs
Expand All @@ -383,6 +408,14 @@ src/crouton.rs reading a Crouton export into import candidates: lines rebui
src/db.rs the SQLite file under /data — WAL on, migrations forward-only
src/entities.rs the HTML entities importers undo in text that was never HTML
src/jobs.rs slow work: two lanes (one for strangers, ADR 0032), progress, results
and an agent's Job, which waits for a Runner in neither lane
and is running while one holds it, with a Job Key minted
each time a Runner takes it. The hold has a deadline, and
a Job is tried a fixed number of times. It is cancelled
waiting or held. One reading an Original waits with no
recipe until its agent creates one, unless it reads a
recipe again (ADR 0048, #261, #262, #263, #266, #267,
#269, #273)
src/language.rs a Branch's Language, read off the recipe's own text (ADR 0006)
src/meaning.rs Meaning Search: the model Kamosu does not ship, and the
index it builds from the recipes (ADR 0029)
Expand All @@ -397,6 +430,15 @@ src/step_uses.rs which Ingredient Lines a Step uses, by the short names
recipes call them after the list (#184). A short name
holds the name's main word, which sits at the end the
Branch's Language puts it (#212)
src/page_text.rs the text of a page's own article, found as a reader
would and written out as a browser copies it, for a
link with no recipe data on an instance with no
Runner (#301)
src/runner.rs the Runner: `kamosu runner`, which asks one Kamosu for
Jobs and starts an agent command in a fresh folder for
each, or hands each to an agent at a Unix socket. Its
client is its own, apart from the guarded one (ADR 0033,
ADR 0048, #274, #317)
src/pdf.rs the text out of a recipe PDF, for the paste reader; a
scan holds none and is refused (#176)
src/web_door.rs Axum router generated by walking the Catalogue
Expand All @@ -410,6 +452,10 @@ src/design_tokens.rs embeds and serves the generated stylesheet, fonts and icons
src/interface.rs embeds and serves the built Svelte app; owns the fallback
tests/parity.rs both Doors materialise every Operation — drift breaks the build
tests/behaviour.rs behaviour through real Doors against a real database file
tests/runner.rs the real program started as a Runner beside a test
Kamosu, with a stand-in for the agent: a command, or
one at a Unix socket started again after each Job as
its container is (#274, #317)
tests/*_corpus.rs the same, against the real 86-recipe Crouton export —
#[ignore]d, since samples/crouton/ is personal and gitignored:
run with `cargo test --test <name> -- --ignored`.
Expand All @@ -426,6 +472,13 @@ ui/ the Svelte app; ui/src/app.css is the design tokens' source
ui/tools/ the dev tools `just` runs against the dev instance: sign in,
photograph screens, capture and serve a prototype (#216).
The two release commands live here too (ADR 0047)
agent-image/ the agent beside a Runner, in an Alpine image of its own,
which every release publishes as battermanz/kamosu-agent
and builds again only when this folder changed:
opencode, the tools a Job needs, the instructions it
follows, and the program that takes one Job from the
Runner through a socket and ends (#315, #317, #345,
docs/runner.md)
docs/releasing.md the release runbook
docs/docker-hub/ the Docker Hub page of the image: its overview and its one-line
description, published by a release and never edited on
Expand All @@ -445,6 +498,25 @@ Catalogue and both Doors grow it in the same commit.
as REST destroys the parity guarantee; don't.
- **A permission check written inside a Door is a bug.** Authorisation happens
once, in the Core, keyed on the Credential. Doors only carry the Secret.
- **What a Job Key may call is the `job_key` mark on each declaration, and that
mark is a security boundary** (ADR 0048). A new Operation is `JobKey::Never`.
Marking one for a Job Key takes a decision of the ADR's weight, and
`the_job_keys_list_is_these_operations` in `tests/behaviour.rs` fails until
the name is added there on purpose.
- **A Job Key's write is held to its Job's recipe in `Core::execute`, never in
the Operation** (#264). The mark says which: `WritesItsRecipe` names the
recipe in `branch_id`, and any other recipe answers as one that is not
there. `CreatesItsRecipe` creates the recipe of a Job that has none, once,
and the Core makes it the Job's own (#269). Where the asker's own change
would start a Copy, the write is refused and the Job fails. No Operation
decides what a Job may reach. A Job Key may use two routes outside the
Catalogue: `POST /api/photographs`, by the mark on `upload_photograph`, and
`GET /api/originals/<job_id>` for its own Job's Original.
- **A save knows which Job is writing, and that is all any Operation knows of
Jobs** (#265). `save_onto_branch` writes it on the Version's row beside the
Access Key, folds a Job's saves into the one Version that Job wrote, and
refuses a save that would leave a second, failing the Job. This is about
how many Versions a Job leaves, never about what it may reach.
- The MCP door speaks revision `2026-07-28`, stateless, no handshake.

## Changing what a recipe holds
Expand Down
Loading
Loading