almogbaku/aos/init

init

Init is not done until the cron jobs exist (or their degraded run-cards do). An unscheduled base means an undrained queue and an unenforced contract, which is worse than no base at all.

1. The structure interview

Ask once, design once — the user is never bothered about structure again. Afterwards the agent operates autonomously inside the frozen zone set, and a zone change is an owner-approved .kb/base.yml edit.

• Name, path (default ~/<name>-base), remote (optional), audience

(private default, or shared), sync (rebase-5min or manual).

• `rebase-5min` requires a remote, and nothing enforces that — stop and get one if the

user wants it. kb init --sync rebase-5min with no --remote succeeds, and the resulting cron then reports synced (no remote) and exits 0 every five minutes forever, syncing nothing. No remote yet? Choose manual and switch later.

• Purpose — one paragraph. It is the rubric for both routing and recall. Write it well.
• Theme → zones and types. An engineering base wants different zones and types than a

family or self base. Start from the template defaults and adjust with the user. Anything they say about what belongs where is routing gold: it becomes purpose prose and routing.keywords.

• Curation — on a shared base, who reviews what agents propose? self means each

person curates their own captures (the default, and right for most teams); designated names one curator who drains everyone's. Private bases are always self.

2. Scaffold

kb init <name> --path <path> --audience <a> --sync <s> --purpose "<p>" \
  [--remote <url>] [--curation designated --curator <principal-id>] [--default]

The tool clones a template repo by default (read-only, unauthenticated, no fork) and drops the clone's own history before rendering; --template <url> points at a different one, and --templates <local-dir> skips the network entirely, which is also the automatic fallback when a clone fails for any reason — announced, never silent, never blocking.

It renders the templates, git-inits, registers the base in <aos_home>/.aos/kb-registry.yaml (creating it if absent), and commits. On a machine with no identity yet it saves a typed --principal to <aos_home>/.aos/kb-principal.yml — never AOS_PRINCIPAL_ID; with one saved, a typed flag authors this init only and the file is left alone (kb config set principal.id= changes it). A write verb with no resolvable identity — neither flag nor file — errors, naming the file. Read-only verbs (kb lint, kb find, etc.) need no identity. It does not touch the repo's git identity: the user's own identity authors every write and the acting agent is recorded as committer.

Then apply the interview's zone and type adjustments with kb config set (for example kb config set 'zones.decisions={kind: wiki}'), which commits each change itself, and create the matching directories. Show the user the diff. A hand-edit of .kb/base.yml also works but leaves the tree uncommitted, which lint reports as a finding — so follow one with kb commit --verb config --path .kb/base.yml --summary "<what changed>".

3. Cron jobs

Three jobs, and init is not finished until all three exist. The harness cheat-sheet's mapping.cron gives the exact command for this harness; what does not vary is what to schedule:

The environment column is not optional, and it is the column people drop. A cheat-sheet puts it in the job's own env, a wrapper script, or an export before the command — whichever your harness supports; what matters is that the job carries it. Every one of these fails quietly: the job runs, the work happens, and the damage surfaces days later.

Two things silently break if you skip them, and each fails quietly rather than loudly:

• `AOS_AGENT=agent:archiver` in both archiver jobs. It defaults to agent:main, which

holds no write grant on entities/** concepts/** projects/** index.md — so a job that looks like it worked commits every promotion as the wrong subject, and the next weekly lint reports each one as a grants-audit critical.

• The single-owner rule: each of these runs in exactly one harness, so check none of

them already exists before creating it.

No cron on this harness? Then all three degrade to manual run-cards: write down the command and the trigger for each ("run kb sync --all when you finish a session"; "ask the archiver to promote overnight"), and tell the user, because nothing will run them otherwise.

4. Verify

kb lint must report zero Critical and zero Findings on the fresh tree (Info lines are fine — they are observations, not defects). Report back: the tree, the grants, the registry entry, and the cron jobs or their degraded modes.