aula-cli
AGENTS.md0 starsChanged 54 days agoMITView on GitHub
Read-only CLI over Aula (aula.dk), run by an agent on behalf of a non-technical parent. GOALS.md says why and for whom; read it before a design decision. API.md is the wire reference, including Aula's failure modes, nearly all of which return a successful-looking response; UPSTREAM.md is the short version of it that ships inside the binary, for an agent with no checkout — aula --upstream prints it. BRIEF.md is the daily brief's design; SETUP.md the install runbook; HOSTING.md the hosted…
- Reads credentials
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
The file
We split this AGENTS.md into the rules it gives an agent
8 rules. About 0 are common, 2 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 3
Read-only CLI over Aula (aula.dk), run by an agent on behalf of a non-technical parent.
- Very specific: line 18
Every feature is implemented in a worktree: Create it before the first edit (the EnterWorktree tool, git worktree add ../aula-cli-<feature> …
- Very specific: line 153
Real family data never enters tracked files: Before writing a fixture, a test, an example, a doc or a commit message, read …
- Distinctive: line 199
Leave none of it to be translated at runtime.
- Very specific: line 246
Every
claudesubprocess pins--modeland--effort: Leave one out and the call does not fall back to anything neutral: it takes the … - Very specific: line 288
All of it is affordable only because --catch-up answers a settled slot from one file read without opening a socket, so do not add work …
- Very specific: line 373
An answer is as old as its oldest part, and says so: Every cached response is stored with the moment it was fetched (Stamped in cache.ts), …
- Very specific: line 419
A list that was cut says so, in the payload: Every command that takes --limit prints { <rows>, truncated, limit } through emitList, and the …
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Working on aula-cli
Read-only CLI over Aula (aula.dk), run by an agent on behalf of a non-technical
parent. GOALS.md says why and for whom; read it before a design
decision. API.md is the wire reference, including Aula's failure
modes, nearly all of which return a successful-looking response;
UPSTREAM.md is the short version of it that ships inside the
binary, for an agent with no checkout — aula --upstream prints it.
BRIEF.md is the daily brief's design; SETUP.md the
install runbook; HOSTING.md the hosted copy — a Cloudflare Worker
with its own login, in src/hosting/.
Working agreements
How I want work done. The hard rules below are this project's own and win where they conflict.
Every feature is implemented in a worktree. Create it before the first edit
(the EnterWorktree tool, git worktree add ../aula-cli-<feature> -b
<feature>, or an isolation: "worktree" subagent); this checkout is for
reading and merging only. I run several agents at once and they would otherwise
overwrite each other. Removing the worktree and branch is part of the merge, not
a follow-up — if one is dirty, show me the diff instead of force-removing it. On
my machine a PreToolUse hook blocks edits made in this checkout; if you hit
it, you skipped this step.
Commit at every completed step of the plan, once bun test src/ and
bun run typecheck pass, and merge back into main as soon as the whole
change is green. Both are standing authorization, no need to ask — a
finished change parked on a branch goes stale, and the other agents working
alongside you cannot see it until it lands, so do not leave one sitting in a
worktree waiting for me. Pushing and PRs still wait for me.
Keep technical debt low; do not preserve backwards compatibility. I am the only user, so breaking changes are encouraged wherever they simplify — with the public-repo hard rules below the one thing that never bends.
Exit codes
The fleet's shared table, as of the change that adopted it. This repo used to have its own colliding scheme (1 usage and bug, 2 credentials, 3 API error), which meant an agent driving several of these tools could not branch on a code without first knowing which tool produced it — and the fleet doc spent five lines saying so.
| Code | Meaning |
| 0 | success |
| 1 | Aula is down or blocking, or a bug in this client |
| 2 | usage error |
| 4 | resolved, but nothing to report |
| 5 | no usable session, or setup — never fixed by retrying |
They are the public contract, shared with cvr, bolig, tinglysning and
dgs and recorded in ../contract.json; change them only in lockstep with
that file and ../AGENTS.md.
Every exit without a body ends stderr with the error line —
{"error":{"code","message","hint"}}, one line of compact JSON, after whatever
prose came before it. The code is on the error class (CliError.errorCode), not
worked out from the message when it is printed, and the exit follows from the
code (EXIT_FOR), never the other way round. It used to be worked out from
nothing: the catch chain picked an exit by instanceof, everything else an
agent could branch on was prose, and a laptop with no network got a raw stack
through the "bug in this client" branch — fetch rejecting is now NETWORK.
Codes are USAGE, SETUP, NETWORK, UPSTREAM and BUG; no BLOCKED,
because Aula has no bot wall this client has met. A site that prints its own
prose and returns a code calls failWith; ensureErrorLine is the net under a
forgotten one. doctor is the one exit 1 that also has a body. On stdout, JSON
is one line unless a terminal is reading it (toJson).
Exit 5 never tells the reader to log in. It said "Run a MitID login: aula
login", and the reader is usually an agent, which took that as the next command
— a login costs the user an approval on their phone, and an abandoned one trips
MitID's parallel-session detector for the attempt after it. sessionGuidance
and sessionHint in auth.ts are the one wording: what still answers without
a session (SESSION_FREE_COMMANDS, each run without a login by cli.test.ts),
and that the user is asked before aula login. AulaAuthError appends it to
every credential failure, so a throw site cannot forget it. The skill and
SETUP.md say the same thing in the same words.
aula --contract prints this tool's slice of that file, as every sibling
does — it was Unknown command "--contract", exit 2, while the fleet's own
instructions said each tool answers it. src/contract.ts imports the vendored
contract.json rather than reading it, because the compiled binary has no
checkout beside it (see Releasing). No join_keys in the output: this tool sits
outside the join graph on purpose.
The output is the fleet's one frame, so an agent can learn it from any tool
and reuse it on the next — two tools printed two shapes before contract 7.
contract, tool (the frame is otherwise anonymous: two outputs side by side
could not be told apart without reading repo), exit_codes, body_on,
error_codes, the shared error_body and stdout sections verbatim, then
commands and the rest of the slice. exit_codes is an OBJECT here, not the
slice's bare array: the array in contract.json says which codes this tool
emits, and the frame expands each to its meaning from the shared table, cut to
that list — five integers leave the reader looking for a table they do not have.
The table's own _note is dropped in the cut; it is not a code, and what it
says is answered by the body_on beside it. contract.test.ts asserts the key
set and the cut, cli.test.ts asserts the process prints them.
Since contract 7 the slice declares every agent-facing command — keys, nested
by jq path, nullable, on_exit_4, notes, and the error_codes the error
line can carry — and src/contract.test.ts holds each declaration to the output
the code produces against the fake Aula, in both directions: a declared key that
is missing fails, and an emitted object nothing declares fails. Change a shape
and the slice, or the test says which side is wrong.
Exit 4 is returned, not just declared. It sat in EXIT, the skill and the
contract while nothing emitted it — Object.values(EXIT) was all that kept the
contract test green — so an empty inbox left at exit 0. emit takes a
nothing flag and emitList derives it; the body is still printed, because
body_on is [0, 4]. Pass it only on positive evidence of emptiness: not for
one page of a thread, not for a vendor plan whose status is failed, and
never for digest. A capability no school offers (NoProviderError) is 4 with
[]; it used to be a stack trace at exit 1.
A vendor plan states its status, and a read that failed outright is exit
1. A failed fetch and a quiet week are the same items: [] on the wire; the
difference lived in whether warnings happened to be non-empty, which the
skill told the agent to check in prose, and which the one warning that is not a
failure ("the vendor was not asked") got wrong. graded in
integrations/index.ts stamps ok / partial / failed / skipped; the plan
commands (emitPlans) print a body at exit 0 or 4 when anything is readable or
nothing failed, and exit 1 with no body when nothing readable came back and a
vendor failed — the vendor's reason goes to stderr. digest never exits for
one part; its weeklyPlans[].status is what cannot be misread.
Who typed the method name decides the code. AulaMethodError — the
read-only guard refusing a name, or Aula answering 404 for one — is exit 1 from
a typed wrapper, where it is a bug in this client, and exit 2 from raw, where
the caller chose it. Both were 1, so an agent that asked raw to send a message
was told a source was down and to retry. A failed login and a lapsed
refresh-stepup are 5; they were a literal 2 left over from the old scheme.
--json is accepted everywhere and ignored. JSON is already the default
here; the flag exists so an agent driving the whole fleet does not have to
remember which tool wants it and which rejects it. It used to be a hard error
with empty stdout.
Every argv mistake is a UsageError. parseArgs runs with strict: true
and throws a plain Node TypeError, which escaped into the "this is a bug in
the client" branch and printed a raw stack — a mistyped flag was byte-identical
to a crash. parseCommandLine wraps it.
Hard rules
- Never write to Aula.
assertReadOnlyinclient.tsandwidgets.tsenforces it before a socket opens. Do not extend the allowlist or route around#requestto try something;presence.updatePresenceTemplateis absent on purpose. - Never perform a MitID approval. That is the user's phone and identity.
Real family data never enters tracked files. Before writing a fixture, a test, an example, a doc or a commit message, read
data/private-terms.txt— a gitignored, hand-maintained list of the real names of this family, the people around them, their institutions and their identifiers. Nothing on that list may appear anywhere in tracked content. This repository is public. Being inspired by a live Aula response is fine; pasting one is not — change the names, the class, the institution and any signup code before it lands. Invent a name rather than borrowing one, and check the invention against the list first: the fictional cast once reused names that turned out to belong to real people in the class. Fixtures and docs use the fictional Eksempelsen family witheksempel.dkvalues; anything real goes in the gitignoreddata/. Add to the list the moment a new real name appears, and never move a term out of it into a tracked file.bun run scan:privatechecks every tracked file against the list (from a worktree too) and prints file and line only; run it before committing anything that touched a fixture, a test, a doc or an example.One exception, the user's own decision (2026-09-23): the images in
src/hosting/public/— the hosted login page's logo and the site icons — are the family's own wordmark, which is built from its name. The exception is those image files and nothing else: the name stays out of text,altattributes, file names and commit messages, and a new image is not covered by it without asking.- Preferences are the model's to read. The model interprets the prose in
preferences.mdand returns a typed relevance verdict; ranking code acts on that verdict. Do not parse preference wording in code. - Tests never touch
~/.aula.bun test src/stays credential-free: this repo is public, and a test that refreshed a stranger's token would also break anyaularun beside it.src/testing/seed-tokens.tsrefuses to run withoutAULA_DIRpointed at a scratch directory; do not work around that.
Code is English; Danish is what the reader sees
Everything a parent reads is Danish, and Danish belongs nowhere else: rendered
page text, CLI output, prompt prose, diagnostics that reach the page, and the
questions an agent puts to them on our behalf. Identifiers, type names, keys
(including JSON exchanged with the model), data-* attributes, CSS classes,
sentinel values, comments and test names are English.
- What an agent says to the parent is parent-facing copy; the document it
reads to know what to say is not.
SETUP.mdis English, for the agent following it. Its feature question first said to ask "in the language the user has been speaking" — so an agent that had just read several pages of English asked a Danish parent in English, and handed them a checkbox list to answer in a language nobody in the family had used. Every line the parent's own eyes land on is therefore written out in Danish in the document itself. Leave none of it to be translated at runtime; that is the step that gets skipped. - A Danish external contract is mirrored verbatim and mapped at the
boundary;
min-uddannelse.tsis the pattern. MinUddannelse really does sendkuvertnavn,ugebreveandhold: [{ navn }], and its schema is public athttps://api.minuddannelse.net/csv/metadata?op=OpgavelisteRequest(no token; some otherop=values 403). Check it before typing a payload; a fixture written from our own type can make a wrong field name look correct. - Aula's API is English even though its UI is Danish. The wire says
activityType,commonFiles,institutionProfileIdwhere the screen says "Henteform", "Fælles Filer". Name code after the wire; mention the Danish label only where it helps someone find the feature. - Our own vocabulary is English. A card's placement is
upcoming,undated,past; what the page shows is Kommende, Uden fast dato, Tidligere — never the headings in code. Where both must exist, keep them side by side —cli-helpers.tsmaps presence codes through{ da, en }. - Danish quoted as a specimen of input is not a name:
rules.tsmatches literal "på mandag", so the comment showing it stays Danish.
A widget the family does not have cannot be exercised from a normal account:
Aula mints a token for any widgetId and the vendor then answers 403 Token is
invalid (Person not found …). scaarup/aula and Casperjuel/aula-mcp are the
fallback sources.
Non-obvious behaviour
src/hosting/is insrc/and never in the binary. It is the hosted copy's Worker, deployed withwranglerfrom a checkout; nothing the CLI imports reaches it, so the compiled binary carries none of it. It lives here so Bun typechecks and tests it, which is why it declares the slice of the Workers runtime it uses instead of loading@cloudflare/workers-types— and why its entry module exports nothing but the handler and the Durable Object class: workerd refuses to start on anything else, and a dry-run bundle does not notice. Who may sign in, the sender and the upload token are Worker secrets; no address and no token belongs in a tracked file. Run it underwrangler devbefore merging a change to a route or a header — the unit tests set request headers by hand, and the two bugs they missed were both headers a real browser sets.- Every
claudesubprocess is started in~/.aula/cwd, an empty directory of our own.claudetreats its working directory as a project, and an inherited one is a decision nobody made: under launchd it was/, so every scheduled model call opened a session rooted at the boot volume, and macOS asked the family to approve aula for their Photos library, Music library, Desktop and Documents. Run by hand it was whatever checkout the user's shell was in.spawnClaudesets it, rather than the plist, because that fixes the interactive case too. The directory must stay empty — that is what makes it boring — andsrc/llm/claude.test.tsfails if anything writes there. - Every
claudesubprocess pins--modeland--effort. Leave one out and the call does not fall back to anything neutral: it takes the account's default model and theeffortLevelin~/.claude/settings.json, and--safe-modedisables neither — the same decision-nobody-made as the working directory above. The brief ran that way until 2026-09-28, on Opus 5 atxhighbecause that was the user's setting for interactive coding; the request was read off the wire through a loopback proxy onANTHROPIC_BASE_URL, because neither the stream-jsoninitline norANTHROPIC_LOG=debugprints the effort.MODEL_SETTINGSinclaude.tsis the one table, and a model newer than the installedclaudefails with a 400 that names the minimum version. --allowedToolspre-approves;--toolsis what removes a tool. Measured twice now: an allow-list alone still let a session read any file.--toolsstrips the built-in set only — every tool of every connected MCP server stays in the list regardless, so a calendar read is offered Gmail'ssend_messageand Drive'sshare_file. They are not pre-approved, so a headless run cannot call one, butconnector.tsalso denies the Google Calendar connector's four write tools by name, because a read-only promise kept only by the prompt is not kept. A baremcp__prefix denies nothing;--disallowedToolsmatches real server and tool names only.bunfig.tomlpreloadssrc/testing/test-setup.ts, which points$AULA_DIRat a scratch directory. "Tests never touch~/.aula" used to be kept by convention — every test passed an explicit path — and the first code to derive a path itself broke it on the first run.AULA_DIRis resolved at module load, so this cannot be done from inside a test file.- The schedule's unit is a slot, not a day.
aula scheduleinstalls 06:00 and 18:00, every day of the week, andslots.tsdefines the half-open interval each one owns — 06:00 until 18:00, then 18:00 until 06:00. Every instant belongs to exactly one, which is what gives a laptop opened at 14:00 something to ask about. The ledger check wastodayIsCompletewhile there was one run a day; at 18:00 that read the morning'scomplete: trueand the evening overview could never have existed. - The plist has three triggers, and
launchd.plist(5)is the opposite way round from what the names suggest.StartCalendarIntervalfires at the slot times and is the wake-up catch-up: a firing missed during sleep is started the next time the Mac wakes, several coalesced into one.RunAtLoadcovers the Mac that was switched off, where nothing was loaded to be overdue.StartIntervalis dropped outright during sleep — the man page blames kqueue(3) — so it catches up nothing; it covers the awake Mac whose coordinator died with the slot's own firing already spent, and it replaced a grid of retry entries thirteen times its size. Do not attribute the wake behaviour toStartInterval; that was wrong when first written here. All of it is affordable only because--catch-upanswers a settled slot from one file read without opening a socket, so do not add work before that check. - A spent retry window is written to
state.jsonasexhaustedSlot. The coordinator's three hours start at the first attempt that ran, so a Mac that wakes at noon still gets all of them — which means a later process cannot recompute the window and has to be told. Without it the heartbeat hands a permanent failure three fresh hours every fifteen minutes until the next slot. It is anchored to the slot rather than kept onlastRun, so it expires by itself and no later run can clear it. - The slot times are in
~/.aula/config.jsonas well as in the plist. A plist cannot be asked what it says, and the run a heartbeat starts has to know which slot it is in.aula schedulewrites both, config first. - The calendar session must be told to wait for its own connector:
MCP_CONNECTION_NONBLOCKING=false. A claude.ai connector is not configured on disk — the CLI fetches the account's server list fromapi.anthropic.com/v1/mcp_serversat startup and connects each one — and by default that whole leg is fire-and-forget ([MCP] claude.ai connectors running fully async (nonblocking)inclaude --debug-file). The session's tool list and itsinitenvelope are assembled without it. Measured here: the fetch lands ~380ms in, the prompt long before that, and six runs in seven reportedmcp_servers: []and never called the tool.aula calendarstherefore told a user with Google Calendar connected that it was not connected, whileclaude mcp listsaid✔ Connected— the seventh run won the race and worked, which is what kept it looking intermittent.connector.tssets the variable; nothing else needs it, and the brief's ownclaudecalls should not buy the round-trip.mcp_servers: []in aninitline is not evidence that a connector is missing — it is equally the account list never having arrived, whichANTHROPIC_API_KEYin the environment also causes by taking precedence over the claude.ai login. - MCP tools are deferred in a headless run, so a prompt that forbids other
tools must exempt
ToolSearch. The session lists an MCP tool's name and withholds its schema untilToolSearchasks for it, so "call no other tools" forbade the only route to the tool it was demanding. - A connector's
statusvocabulary isconnected,pending,needs-auth,failed,disconnected.needs-authis the lapsed Google grant — the one state where "reconnect it" is the right advice — and it used to fall past the status check and come back aslist_events blev aldrig kaldt. - Both connector reads are paginated, and each page is a whole
claudesubprocess.listAllPagesfollows up to four.list_eventsused to ask for 250 and treat anextPageTokenas fatal, so a busy shared calendar lost its fortnight rather than its 251st appointment;list_calendarsnever read the field at all and the connector's default page is 100, so a long calendar list silently lost its tail — which surfaced two commands later ascalendars setrefusing a name that plainly exists. Ask forpageSizeexplicitly. - A partial calendar is partial, never empty.
loadPersonalEventscatches per calendar and per event: one appointment whose shape this code cannot read used to escape to the per-calendar catch and cost the family the whole fortnight, reported as an unreadable calendar. The per-event warning is one line with a count, not one line per event — a wholly unreadable calendar would otherwise write two hundredDatastatuslines onto the page. - The calendar session's read-only promise is kept by an allow-list, not only
by
--disallowedTools.attemptToolrejects a session that called anything beyond the one tool it asked for plusToolSearch.WRITE_TOOLSis still named by name because that is all--disallowedToolsmatches, but it goes stale the moment the connector grows a fifth way to write; the allow-list does not. The module header promised this check under the nameexpectedCallsfor a long time before it existed. doctorreads the configured calendars for real. A lapsed connector otherwise passes every Aula check, acceptsaula schedule, and drops the calendar half of the brief at 06:00 with nobody watching — and a page with no appointments on it is indistinguishable from a quiet fortnight. It warns rather than fails (every Aula read still works), skips when no calendar is configured, and names a configured calendar that answered with nothing, because that is what a wrong id looks like.- A missing connector is exit 5, not 1. "Setup required — do not retry unchanged": no amount of waiting connects a connector. A wrong calendar name is exit 2. Both used to be 1, which the fleet reads as "a source is down, retry later".
- A model answer has problems and warnings, and only problems retry. A
refused card or a missing calendar verdict is a problem: the run stays
incomplete, the scheduler tries again, the answer is not cached. Dropped
prose whose decision survived — an ungrounded topline or child line, a
verdict's summary — is a warning: named in Datastatus, logged as
brief.model.adjusted, and never worth another five-minute model call. They were all problems once, and one invented "8/9-11" in a verdict summary kept 2026-09-11's scheduled runs retrying the same extraction twelve times. The card repair runs whenever a card was refused, not only when card dates were the only failures, and the rules fallback fills in solely for the sources the refused cards cited (rejectedSourceKeys). - The weekly plan is read for this week and next, and the timetable is
recurrence evidence. PE on Thursday in two consecutive plans grounds husk
idrætstøj om torsdagen and its next-Thursday date without any sentence
saying "hver torsdag"; one week alone is a one-off.
recurrenceWeekdayOfindates.tsis the one reader of that evidence, shared by the validator and the ranker — it was two slightly different copies. - An answer is as old as its oldest part, and says so. Every cached
response is stored with the moment it was fetched (
Stampedincache.ts),ResponseCache.oldestHitAtis the oldest one a process answered from, andAulaClient.dataFetchedAt()turns that into thefetchedAtondigestand on every list envelope.digestused to stamp itselfgeneratedAt: nowwhether it had made sixty requests or none — and "did the teacher reply yet?" is a question where ten cached minutes are the whole answer. An entry written before entries carried a time reads as a miss. statusanswers from disk, and never refreshes anything. It reported the access token's remaining minutes — which renew themselves and say nothing about whether the login works — and read them through the refreshing path, so asking could retire the token of a run beside it. Whether Aula accepts the login is only knowable by asking Aula, sosession-seen.tswrites the answer down whenever a command does:profiles.getProfileContextsucceeding (the bootstrap every uncached read performs, and the only response that states step-up), anAulaAuthErrorat the top level, and a login, logout orrefresh-stepup.statusreads that note back. Aula publishes no lifetime for the refresh token or for step-up, so there is no expiry to report; the last observation, with its time, is the substitute.- Two caches, and
cache statusreports both. Remote responses — Aula, the vendor weekly plans and the Google Calendar reads — share one TTL'dResponseCachein~/.aula/cache/responses; the model's layout is cached separately in~/.aula/brief/cache, keyed on content with no TTL.--no-cachebypasses both, andcache clearempties both. It used to empty only the responses, so clearing to force a fresh brief still served the stored ranking back in ten milliseconds. - Reads are cached 600 s in
~/.aula/cache/responses, so a seconddigestinside the window makes no requests;--no-cacheis the first thing to reach for andcache statusshows what is held. Never cached:aulaToken.getAulaToken, because the vendor-token retry needs a genuinely fresh one, and failed calls, so a transient 403 is not pinned for the TTL.#ensureApiVersionand#ensureSessionbypass the cache deliberately. - The calendar goes through that same response cache, keyed on
{calendarId, from, to}—calendarWindowtruncates to local midnight, so the key is stable for a day. Per calendar, and storing the raw connector answer: one unreadable calendar must not cost the others their entry, andtoPersonalEventis ours to change. Without this, two configured calendars cost ~25 s ofclaudesubprocesses on every run — on a fully warmaula new, essentially the entire runtime. login,logoutandrefresh-stepupdrop the cache — threads cached without step-up under-report the sensitive ones and look complete.- An access token can be refused while far from its
exp: arefresh_tokengrant retires the previous one and the loser gets403+ code20. The client re-reads the token store, adopts a newer token or buys one, and replays once. Keep that order — two runs that both refresh rotate each other's tokens forever. - A list that was cut says so, in the payload. Every command that takes
--limitprints{ <rows>, truncated, limit }throughemitList, and the collectors indigest.tsreturnCollected<T>so the fact cannot be dropped by omission. They were bare arrays, the default cap of 20 applied even on top of a--sincewindow, and the only collector that reported a cut did it through an out-parameter thatbuildDigestalone passed — somessages --full --since 30d, the skill's own example, answered with a fraction of a busy month that read as all of it. A--sincewindow now lifts the default cap. - A presigned URL never reaches a payload.
attachments.tshas always said they must not round-trip through a model — one mangled character is aMalformedSignature403 that reads like a dead login — whiledigest,thread,messages --full,posts,attachmentsandcommonfileseach printed them, a few hundred tokens apiece, and a post's attachment had no download command, so copying the URL out of the JSON was the only way to get it. Payloads carryAttachmentRef(describeAttachments): anindexforattachmentorpost-attachment, and alinkfor the one kind that is a web address rather than a download. A thread's attachments are numbered across all of its messages, which is whynormaliseMessagesis plural and why the index is null for one--pageor an incomplete read —attachmentsused to take--pageand number that page from zero, positionsattachmentthen resolved against the whole thread. contactsrows are ours, not Aula's. It printed the wire object with agroupstapled on — the one command whose keys Aula could rename, and the one carrying the fleet's bridge (--role guardian→address), underpostalDistrict.normaliseContactincli-helpers.tsis the shape now, andcontract.jsondeclares it.family.tsresolves the id sets endpoints want once (postInstitutionProfileIds,childInstitutionProfileIds,institutionCodes); re-deriving at a call site is how wrong-id failures start.- The page starts before any MitID contact.
aula logintakes no arguments: it binds the loopback page (login-page.ts), prints the URL, and only once a username has been typed there does the first MitID request go out. That ordering is the invariant to protect. Collect the username first and the session ages through every minute the user spends finding the link and typing, and an aged, abandoned session is exactly what the CAP008 parallel-session detector looks for. It also makes the page load-bearing: a loopback port that will not bind endsloginrather than falling back, andio.tsno longer reads stdin at all — there is no terminal prompt left to fall back to, and adding one back would reopen both problems. - The MitID QR pair cannot be relayed through a chat — it rotates every few
seconds and is a picture either way. So the page draws it, and since the user
is already sitting in front of the page, the page takes the answers too:
askUsernameandaskIdentityarm one question at a time and resolve when the browser POSTs to it.login.tscaps both waits, with deliberately different ceilings — before the username there is no MitID session to lose, so waiting is nearly free; after it, one is expiring on their side.
Formatting
typescript/await-thenable is off in this repo's test files, and only this
repo's. Every one of the eleven findings was await expect(p).rejects
.toThrow(...), which in Bun genuinely returns a promise that must be awaited —
@types/bun types it as returning void. Dropping the awaits to satisfy the
rule would turn each of those assertions into an unhandled rejection that
asserts nothing. It is scoped to .oxlintrc.json here rather than the fleet
base because aula-cli is the only Bun repo; the rule stays on everywhere else.
The rest of the lint and format config is not this repo's to change.
.prettierrc and oxlint.base.json are copies owned by the fleet root
(../config/), copied in by ../scripts/sync-config.sh and asserted by
src/config.test.ts. .oxlintrc.json extends the vendored base and holds only
what is genuinely local: the src/browser React overrides, the ignore list, and
the two rules above. ../config/README.md says which rules are on and why.
Prettier owns the layout — single quotes, 100 columns, pinned in .prettierrc.
Both sides run that same config: VSCode format-on-save through the Prettier
extension, and agent edits through the PostToolUse hook in
.claude/settings.json, which calls scripts/format-hook.sh. Do not hand-align
code against the formatter; run bun run format (or format:check) instead.
Markdown is in .prettierignore on purpose. The docs are hand-wrapped and their
tables are hand-aligned, and Prettier pads every cell to the widest row. Leave
them alone.
Verifying
bun test src/ stubs fetch; cli.test.ts and auth.test.ts run the CLI as a
process against a stubbed Aula.
The login page can only really be judged by whether a phone reads it. Drive it
by hand rather than holding a live MitID session open; it builds its payloads
with the production buildQrPayloads:
bun scripts/login-page-demo.ts # the rotating QR pair
bun scripts/login-page-demo.ts otp # code comparison
bun scripts/login-page-demo.ts username # the username form
bun scripts/login-page-demo.ts identity # the identity pickerThe two ask modes call the real askUsername / askIdentity and reject the
first answer on purpose: the inline error is the part easiest to get subtly
wrong and impossible to see from a test.
What is tested is the ordering the whole design rests on: cli.test.ts spawns
aula login --no-open, reads the page's address off stderr and asserts the page
answers while the request log is still empty — the page is up, MitID has not
been touched. That flag exists for this; without it login spawns a browser and
the suite opens a window on whoever runs it. The assertion only means something
because fake-aula.ts records requests to hosts it does not know: before it
did, an unwired host fell through to the Aula switch and answered null
silently, and "the log is empty" was a fact about the log rather than about the
process.
Releasing
End users install a compiled binary, not this checkout — they have neither git
nor bun, and on a fresh Mac git is the Command Line Tools stub that opens a
GUI installer. bun run build compiles dist/aula-<platform>-<arch> for macOS,
Linux and Windows plus SHA256SUMS; bun run build --target aula-linux-x64
does one. Pushing a v* tag runs the same thing in CI and attaches the results
to the release, so the asset names in SETUP.md's curl are load-bearing —
renaming one breaks the documented install.
src/runtime.ts is the only place that knows which mode the process is in.
Anything that writes a command into a file somebody else runs later — the
launchd plist, a Scheduled Task, cron lines, the installed skill — must take
its argv from programs() or its spelling from commandPrefix(), never
assume bun src/cli.ts. Both take the runtime as an optional parameter so the
compiled branch is testable from a checkout; use that rather than adding a
mode-specific test path.
New files the binary must carry — templates, fixtures, anything read at
runtime — have to be imported (with { type: 'text' }, or type: 'json' as
src/contract.ts does), not read from disk.
import.meta.dir is a virtual path in a compiled binary, so readFileSync
against it compiles happily and fails only for the user.
The bypass layer
UPSTREAM.md is API.md made reachable. This file and API.md are the
developer-facing wire reference, and both were invisible to the reader who
needed them: end users install a compiled binary and never clone this repo, and
the skill an agent loads is a template embedded in that binary — so every "see
API.md" resolved to nothing on the machine doing the reading. UPSTREAM.md is
the same material distilled for someone holding only the binary, imported as
text by src/upstream.ts and printed by aula --upstream. API.md stays as
it is; it goes deeper and is for whoever has the checkout. Verified from a
compiled binary run outside any checkout, which is the only test of reachability
that means anything.
src/upstream.test.ts holds it to the code, and not by a list of things
somebody has to remember to mention. It reads READ_ONLY_METHODS and
WIDGET_ENDPOINTS — the transport's own guards, which a call is refused for
being absent from — so a new upstream cannot be reached without being added to
one of them, and adding it fails the test until the document says so. It also
parses every fenced aula … command in the document through the real argv
parser, and checks the "already wrapped, do not hand-roll" list against
contract.json's declared commands. AULA_API_BASE and FALLBACK_API_VERSION
are exported from client.ts for this; a bumped version that left the document
saying v24 would send an agent to a path where every method answers 10.
raw may POST to a getter-named method. It was GET-only on top of the name
check, which sounds stricter than it was: Aula models some reads as POST
because the filter will not fit in a query string, so a window the calendar
wrapper does not offer was unreachable by the wrapper AND by the escape hatch
that exists precisely so an un-wrapped read needs no code change. The verb was
never the guard — the method name is, and messaging.sendMessage is refused
over POST exactly as over GET. A typed wrapper still may POST only to
POST_ALLOWED; the widening is scoped to the caller who typed the name.
raw --body '<json>' is the route, and the body must be a JSON object.
TOOL_FLAGS in cli-options.ts is the one list of tool-level flags
(--help, --contract, --upstream, --version, --json): no command, no
session, no request. Both drift tests read it. It used to be a copy inside
skill.test.ts beside three overlapping lists of commands-whose-options-count,
and the hand-written one went stale the moment raw grew --body — a real flag
reported as a flag no command takes.
Finding an unwrapped endpoint
The recipe lives in UPSTREAM.md §7, not here. It was in both, and two
copies of a shell pipeline is how one of them quietly stops working — the one
that ships is the copy an agent runs, so that is the copy to keep. Read it with
aula --upstream, or open the file.
The half that is genuinely for someone with the checkout: the bundle grep gives
you method names, not parameters. In the browser's devtools the store action
shows the request and the component builds the params — grep the mapActions
alias, e.g. ACTION_GET_COMMON_FILES_LIST,append. raw <method> k=v confirms a
guess; a wrong parameter set returns status 40 with no detail about which one.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

