# Dave J Brief: How We Push Starter-Pack Updates To Existing Owners

**Raised by:** Dave W / Claude + Codex review
**Date:** 2026-06-30
**Repo area:** `BrainDrive/builds/typescript/memory/*` (update system), `gateway/server.ts` (prompt injection)
**Priority:** High — blocks how we ship journaling and every future capability
**Related docs:** `update-notification-spec.md`, `update-handler-skill.md`, `runtime-pack-boundary.md`, `dave-j-runtime-pack-boundary-brief.md`, `foundation/page-journal/`

## The Problem

We need to ship improvements (like journaling) to people who *already* run BrainDrive — without overwriting files they've personalized. Owners also run different AI models of widely varying capability, so any update logic that depends on the model to judge "is this safe to merge?" is unreliable by design.

The current draft update system tries to do smart merges (LLM rewrites an owner's customized file, self-rates the risk, auto-applies). That's the fragile path we want to kill.

## The Rule We Landed On: Additive-Only

For automatic updates to existing owners:

- **Add something new to the starter pack → everyone gets it.**
- **Change something that already exists → only new downloads get it.** Existing owners are never touched.

This is deterministic, model-independent, and safe. It removes merges, risk-scoring, and LLM planning entirely. The only state needed is one version number per owner (which release they're caught up to) — not a per-file ledger.

Accepted cost: starter-pack evolution is **append-only** for existing owners. A later fix to an existing file won't reach them automatically. That's fine for V1.

## The Catch (and the real decision for tomorrow)

Most new capabilities aren't self-contained. **Journaling is the example:** dropping in the journal files isn't enough — something has to tell the AI "journaling exists, use it when relevant." Today that means editing an existing file (the fitness instructions), which additive-only forbids.

**Two ways to handle discovery:**

1. **Make the AI find it** — a general instruction: "scan the capabilities folder and apply what fits." ❌ Rejected: this puts a weak owner model in charge of remembering and applying it every turn — exactly the model-quality dependence we're trying to escape.

2. **Make the BrainDrive *app* find it** — the software notices "owner is on the fitness page, journaling applies," and hands the journaling instructions to the AI already loaded ("here, use this"). ✅ The AI doesn't discover anything; it just follows what it's handed.

Like a phone OS surfacing a newly installed app — the software handles discovery, not the user and not a flaky assistant.

## Why Option 2 Wins

- Journaling instructions stay **plain English** owners can read and edit (text-first holds).
- "When does this apply" is decided by **app code** — reliable, identical across every AI model.
- **We never edit anyone's existing files.** The discovery logic ships in the normal **app update** (owners don't customize the binary); the journaling files ship as **added** memory. Additive-only stays fully intact, *and* journaling works — with **no owner-memory migration required.**

This also means we should *not* wire journaling into each page's `AGENT.md` (the current `page-journal` pack-source assumes that edit) — the app injecting it replaces that need.

## Verified Against Live Code (Codex)

- Shipped `base/AGENT.md` has **no** capability-discovery hook today (only reads project AGENT.md, overlays, profile).
- Skills are **not** auto-discovered — runtime injects only explicit project/conversation skill IDs (`server.ts`). "Drop a skill file and it works" is false today.
- So this needs to be built; it isn't already there.

## What We're Asking Dave J To Weigh In On

1. **Agree** on additive-only (only-add files; never modify existing; keyed on one release version per owner)?
2. **Agree** the app — not the AI, not edits to existing files — should decide which capabilities apply and inject their instructions?
3. **Scope** the minimum to ship journaling this way:
   - a small capability definition (`id`, `version`, `applies_to`, `triggers`, `priority`, `conflicts_with`, `status`)
   - app logic to pick applicable capabilities per page and inject their text
   - the genuinely non-additive extras journaling still needs: sidebar/UI surfacing (app code) and summaries/indexes as entries grow (added files)
4. **Spec cleanup:** strike the merge / LLM-planning / risk-scoring sections from the draft update spec; keep the safe transaction parts (backup, report, version cursor).

## Open Question

Is there any near-term capability we'd want to push that *can't* be expressed as "app injects text when applicable" — i.e. that genuinely needs to change an existing owner file? If yes, that's the one case needing a separate, owner-confirmed update lane (same lane we'd use for a security fix).