Make or change an Epicenter app: its collections, actions, UI, code/data container, and private root history. Use when asked to build a personal app, change Capture, Reading, Tasks, or Vocab, set up an Epicenter, copy or share app code, or adapt code from another app on the computer that runs epicenter serve.
90%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
An Epicenter is a marked folder with one private Git repository. Its apps
live in apps/<app>/: code/ is an ordinary Bun project and sibling data/
holds records and settings. The source and live Epicenter use this layout
(ADR-0910, Accepted). Inspect an existing app before editing it. An older
Epicenter needs a separately authorized history and directory migration.
epicenter selects the nearest marked ancestor of the current folder, then
EPICENTER_ROOT, then ~/Epicenter. A computer may hold several Epicenters,
such as one per person. epicenter serve offers MCP at / and each UI at
/<app>/, on the marker's port or 4747 when absent.
<Epicenter>/ one private Git repository
.gitignore .gitattributes local files/caches excluded; optional LFS rules
EPICENTER.md AGENTS.md
apps/<app>/ stable container: folder.path and write lock
code/ one Bun project
epicenter.ts collections and actions
epicenter.test.ts action tests
package.json bun.lock actions' and UI's dependencies
README.md
ui/ UI source
dist/ generated, ignored
node_modules/ supplied @epicenter/app link, ignored
data/ records and settings
tasks/<time>.md
google.local.md this computer onlynew --from <path|url>[#folder] copies committed code into a new container's
code/, without records, Git history, or a remote. It accepts a repository
root, a subfolder, or an app container's code subtree. Provenance is in
code/SOURCE.md. Later source changes are work for the app's owner; there is
no merge-based updater. A copied symlink stays a link. For example,
code/ui/src/theme.css -> ../../../../../theme.css needs a root theme in the
destination Epicenter; new reports links that do not resolve.
Read packages/app/README.md and one existing app before starting. Tasks is
the smallest whole example. Keep private records out of code publication;
publishing needs a separate code-only history, and no command builds it.
Before shaping a collection, decide where its truth is (docs/vision.md,
ADR-0896, ADR-0898), then copy the nearest example in ~/Epicenter/apps:
Tasks for a kept collection, whose files are the truth; Mail for a cached
one, a .local copy of a service with the person's decisions kept beside it
and applied through an action; Messages for a live one, asked each time. An
item from elsewhere moves into a kept collection by transfer: write it with
its source id, then close it at the source. Never keep two writable copies in
step, and never make one app import or call another. Anything under
"Not yet" or "Never" in docs/vision.md needs the owner's yes.
Change an app's code in its own code/. Keep experiments outside the live
Epicenter: a branch switch, stash, or reset there changes every running app's
code and records together. A change useful to another person is a code copy
for their agent to adapt, with any record repair explained beside it.
The files outlive every UI and agent, so their shape is the decision that
matters most. Define each collection with defineCollection({ path, fields })
in code/epicenter.ts: a path template and the fields of each file's front matter
(packages/app/README.md). A collection gives
list|get|add|set|edit|delete (get|set|edit for one file) through
.actions(). An app with one collection spreads them at the top, so they are
its own (epicenter tasks set, MCP tasks_set); an app with several nests
each under its name (epicenter mail messages list). A record's address is
its path: data/tasks/2026-11-10T09-30-00-000Z-k3x9a2f8.md.
A path is one relative .md template under data/, such as
data/days/{day}.md; files in a second layout are a second collection.
defineCollection refuses a path outside data/, a list of paths, or a part
starting with .. A field or placeholder may not be named path,
body, problems, other, json, help, or input.
{time} suits
things made in passing (data/captures/{time}.md, data/tasks/{time}.md): add
names the file by the time. A placeholder add takes suits things named by
what they are (data/words/{word}.md, data/books/{title}.md), at the cost of
characters a file name cannot hold. add and pathOf name the file by the
value as NFC, trimmed, with single spaces, so an action passes what the
person typed.localDay() or localTime() from
@epicenter/app, in the time zone of the computer that runs the action,
as field.date and field.datetime hold them; toISOString() gives UTC's
day, which is the wrong one in the evening west of Greenwich.started and finished say whether
a book is to read, being read, or read.list returns fields without bodies. Put what a list or an agent needs at a
glance in a field (a task's title); put prose in the body.set merges as JSON Merge Patch does: null removes a
field, so a field that may be absent needs no null in its type; a
required field takes no null. A set with no field throws. In a one-file
collection every field is optional or has a default.readOnly when only the app's own actions may write it (Vocab's
schedule, Capture's capturedAt): the exposed add and set leave it out.
A readOnly field that is required with no default removes the exposed
add, so write the app's own (Capture's add).field.text({ pattern, description }), the description
reading after "must be" (Tasks' title: one line, not blank, saying what to do), so the generated set refuses what the app's own add would.problems quoting what was
dropped; get also carries other, the front matter that is not a fitting
field. So every field without a default is optional when read, a required
one included. Read code handles absence; it never assumes the declaration.edit --old <text> --new <text>, which replaces one
passage and is refused unless old occurs exactly once, so a body read
before someone else changed it is never written back over theirs
(ADR-0869). An empty old fills an empty body..local.md path (data/google.local.md), its fields declared like any other
(ADR-0870). A .local file stays on the computer that runs the app:
the root .gitignore leaves it out of every commit, folder makes it 0600,
and its actions() throws, so no generated verb hands it to an MCP client.
Read it in an action with google.get() and write it with google.set(...).
A fresh clone has none, so the person signs in again.other, and a missing optional field
is no problem. Rename or tighten a field in two steps: change the code,
then repair records with an action or agent. Read each record's other and
problems afterward. A checkpoint records both code and repairs together.
There is no global migration gate. Explain any repair when sharing code;
another person's records change only when they run it.For Mail (ADR-0882), agents prepare and revise proposals; the person runs
epicenter mail apply. Never apply a proposal or call Gmail's mutation
endpoints on the person's mail as an agent. Exercise the apply path only
against fake Gmail.
code/epicenter.ts default-exports defineApp({ description, collections, actions }). An app is one Bun project, with package.json, bun.lock, and
node_modules inside code/. Its actions may import anything its
package.json names, plus Node's
built-ins. Add packages with bun add in code/, then run
epicenter install <app> to restore the supplied link, which Bun can remove.
@epicenter/app comes from epicenter and is never listed in the app's
package.json. Its engines.epicenter (">=0.2.0") is the oldest
epicenter the app runs on; epicenter new writes its own version there.
Raise it when the app starts using something a newer @epicenter/app added,
always as a floor (>=), never a caret. epicenter new and epicenter install [<app>] install from
code/package.json (--frozen-lockfile when bun.lock exists) and link that package;
a call never installs. Write each action with defineAction, which types its
run from its input. Add one when the caller cannot do the job with the
verbs: a rule on making a file (Tasks' add splits a title from its notes),
a rule across fields (Vocab's review scheduling), or a read shaped for a
screen (Capture's recent). Replace a verb by key, as in any object:
{ ...words.actions(), add: learn }. Inside run, read and write through the
collection's methods (words.get({ path }), words.set({ path, ...fields }),
words.edit({ path, old, new }), words.update({ path }, change)) instead of
parsing front matter again. For other files, the imported folder supplies
atomic writes and updates. Build a path with words.pathOf({ word }), never by hand.
Make the first write through folder or a collection, so the call takes
container's lock. It stays held until the call returns, throws, or stops.
After that first write, a library or node:fs write shares the call's lock
lifetime. A call with no folder write takes no lock. All writes stay pending
until a named commit or root checkpoint records them.
folder refuses a write outside data/ or through a .git* path segment.
Reads may reach the whole Epicenter, including another app's records by a
path like ../tasks/data/tasks/<time>.md, using node:fs or a library.
Resolve that path from folder.path, which is the container. Change another
app's data through its actions so its rules check the write; this is guidance,
not enforced.
Make run an async function* only when a person watches it work, such as a
chat reply from a model: each yield reaches the page that called it, and no
one else. Return what the call produced, as any action does, since the
command line, Claude, and tests see only the return. Save at the end, before
returning, so a page closed mid-reply leaves nothing half-saved (ADR-0879).
To offer Stop, pass callSignal() from @epicenter/app to the wait, such as
the model's fetch, so a stop ends it at once; what must survive a stop, such
as the person's message, is saved in a finally.
Actions run inside epicenter serve itself, from the files as they are when
the call arrives, so an edit takes effect on the next call. Never call
process.exit, process.chdir, or set process.env in an action: each
reaches every app serve runs.
Writes to one app run at once: a phone, an agent, and the command line can
all call the app at the same moment, and an agent may edit its files
directly. A value computed from get and written with set is last write
wins: a change made between them is lost. Compute it inside the collection's
update instead, which calls change with the record as get gives it
(undefined when there is no file) and writes the patch it returns (what
set takes, without path, plus body when the body changes) only over
that same record, or makes the file from it when there was none; when the
file changed meanwhile, it calls change again on what is there now. Vocab's
review schedules a word this way, so two reviews at once both count, and
Reading's start makes a book or starts it in one update, never get then
add, which two calls at once would race.
await words.update({ path }, (word) => ({ reps: (word?.reps ?? 0) + 1 }));For any other file, use folder.update(path, change), never folder.read
then folder.write. It does the same with the file's text (undefined when
there is none). Either way, keep change a pure function of what it is
given, since it may run more than once; throw in it to refuse, and nothing is
written. A collection's change that returns {} leaves a file as it is,
so Reading's start returns {} for a book already started; throw in it
when the record must already be there.
await folder.update('data/2026.csv', (text = 'day,minutes\n') => `${text}${day},${minutes}\n`);Every collection write goes through folder.update. set writes the values
it is given, and folder.write is for a file whose whole content the action
decides: for both, the last write wins.
The generated verbs address a record by its path, the one address every
collection has. An action you write chooses its own input, and one people type
should take what they type: Vocab's review could take { word, grade } and
call words.pathOf({ word }), giving epicenter vocab review 你好 good.
Annotate honestly. A read-only run takes no lock. Its folder writes throw
except to .local paths under data/, so an action that only reads can refresh
a token locally. Actions make no commits. The root ignore rules keep local
files out, and a checkpoint refuses local credentials Git would include.
Write last. A call holds its app's lock from its first write until its
end, and other writes to the app wait for it at most 30 seconds, so fetch
from a service, call a model, or compute first, then write. When the person's
input must survive a failure, write it after the slow step fails, not before
it starts: Vocab's practice reply asks the model, then saves both turns, or
saves the learner's turn alone and throws. Never run epicenter against the action's own app
after writing: the inner call waits for the lock its own caller holds, and
fails after 30 seconds.
After direct edits, epicenter checkpoint -m "<what changed>" records pending
code and records in one root commit and pushes origin when set. A plain named
Git commit works too. The branch and index are shared: checkpoints consume
staged work along with other included files. Make a named commit before a
risky change. Serve runs the same checkpoint at startup, every five minutes
after a scheduled pass completes, and on stop. It samples files, not intent,
and can capture a partial edit or part of a running action.
The root origin is optional and private. It receives all apps' records.
Checkpoints never pull, merge, rebase, or force-push. A failed push leaves
commits local for a later retry. Missing or broken code does not hide data
from a checkpoint. Keep local credentials ignored and never force-add them.
Never run git clean -x in the Epicenter: it deletes local credentials.
To recover, inspect Git history, then restore selected paths from the root:
git log --oneline -- apps/<app>/
git restore --source=<commit> -- apps/<app>/code/ # code only
git restore --source=<commit> -- apps/<app>/data/ # records onlyA whole apps/<app>/ restore reverts both and deletes tracked files added
later. Inspect the root MIGRATION.md and the commit tree first. Commits from
before a move into apps/<app>/ use the old paths. An imported per-app commit
can hold only code or only records: restore its code or data prefix, not the
whole app. History retained only in archive refs is outside main; fetch it
explicitly into a separate recovery checkout. Keep the live home on its
current branch.
Copy an existing app's code/ui/ into the new app's code/ui/: Svelte on Bun's bundler, with ui/build.ts,
the Svelte plugin beside it (ui/svelte-plugin.ts), the hash router in
src/lib/router.svelte.ts, and a manifest and icons in static/; copy
bunfig.toml with it, whose peer = false keeps a peer named bun from
shadowing Bun. The app's code/package.json names every package the UI imports,
from npm, never workspace: or catalog:. The UI imports Epicenter only
through @epicenter/app/client. It owns its components, copied into
src/lib/components/ui/ with components.json, src/lib/utils.ts, and the
theme in src/app.css (ADR-0874). Add a component by copying it whole,
dependencies and tests included, and change it in place.
Build paths are relative to code/. Component paths starting with src/ or static/ are relative to code/ui/.
serve builds the UI itself from ui/ as it sits on disk, committed or
not (ADR-0880). The build runs in the app's code/
folder: when the app's package.json has a build script, serve runs it
with EPICENTER_OUT naming the folder to write; otherwise it bundles
ui/index.html and the TypeScript and CSS beside it, so a tiny UI needs no
package.json. Either way the build writes relative URLs and is never told
where it is served, and @epicenter/app comes from epicenter, linked into
node_modules/ before every build; never list it. serve serves ui/dist/
and looks nowhere else. A build never installs: after adding a package, run
epicenter install <app>.
A change under ui/ shows at /<app>/ on the next page load after its
build, and the last good build stays up meanwhile. A build that fails is not
tried again until a file under ui/, package.json, or bun.lock changes;
run epicenter build <app> to build now and see the build's errors. Never
commit ui/dist/. The UI owns unfinished input and local interaction state.
Actions own stored records; the UI shows what serve answers and sends what the
person submits.
src/lib/app.ts is the one place the UI names the app's actions. It calls
connect<typeof app>() from @epicenter/app/client, importing the app
as a type (import type app from '../../../epicenter.js'), and lists what the
pages watch and what they change with Wellcrafted (see query-layer):
const app = connect<typeof tasksApp>();
export const reads = resultQueries(['tasks'], { list: app.list, get: app.get });
export const writes = resultMutations(['tasks'], { add: app.add, set: app.set });For a run that should continue after the page closes, use
import runs from @epicenter/app/client and use
runs.start(app.action, input), runs.attach(app.action, id), and
runs.pending(app.action). These controls preserve every app action name.
field.file() accepts a temporary browser upload through these run controls;
it does not store a collection attachment. See the app package README for the
run events, cancellation, and retention contract.
Each call answers a Result: what the action returned, or a shared ActionError:
Changed, Missing, Threw, Refused, Unreachable, or Stopped. Use the
factories from @epicenter/app in actions. Check the name and its subject, never
the message. A Missing may describe a dependency rather than the record being
shown. An error does not establish what was saved or rolled back; reread the
record when the outcome is uncertain and retain unsent writing. The layout creates one
QueryClient from the UI's own @tanstack/svelte-query, with the invalidation
rule from query-layer, and puts it
in <QueryClientProvider>; pages read with
createQuery(() => reads.get({ path })) and write with
createMutation(() => writes.set). That client refreshes every read after
each write, before the write counts as done, and when the UI is shown
again, so a page never refreshes by hand or on a timer. Name
types with ActionInput<typeof app.actions.set> and
ActionOutput<typeof app.actions.get>.
An action that yields takes onYield after its input, to show its work as it
comes: app.chat.say({ message }, { onYield: (token) => (draft += token) })
resolves with the same Result once the reply is whole. Pass it where the page
keeps its draft, and make that call the mutation's function, so every read
still refreshes once it returns. A Stop button passes { signal } too and
aborts it; the call then resolves as the Stopped error, which is not a
failure to show.
Route a record by its whole path: the page is at #/data/tasks/<time>.md,
linked with each part URL-encoded
(path.split('/').map(encodeURIComponent).join('/')) and read back with the
router's currentPath(). Write no code that knows the app's templates; show
a record's name from its read (row.word).
Show a record's problems quietly where the record is shown, and never
crash on a field that is absent.
It is a phone Home Screen app first: safe-area insets, 44 px targets, 16 px inputs so iOS does not zoom, light and dark from the system.
Send set only the fields being submitted, and null for one emptied.
Do not spread an entire cached record into a field update. Comparing with
cached data can avoid a request; it cannot establish what is currently saved.
When draft, recovery, or workflow promises are unsettled, use product-collapse to choose the behavior. For settled behavior, choose each input's owner with input ownership. Writes also arrive from other tabs, agents, and the command line; blocking local edits while pending prevents only this page's overlap.
Use edit with its quoted base (old: base, new: draft) when the app promises
conflict detection. On Changed, reread and preserve the submitted text
while resolving the conflict. When last-write-wins is accepted, use the app's
replacement action without adding rebasing or a recovery queue.
Show a write before it lands from the mutations still pending:
useMutationState({ filters: { mutationKey: writes.set.mutationKey, status: 'pending' } }) (Tasks' done, Vocab's review queue, Capture's adds). When the
write settles, the refreshed read takes over. Say a failed write in a toast
with error.message.
Save on blur, on a pause, or on an explicit action, never on each keystroke. Checkpoints sample those files later; a call is not a commit boundary.
Never run anything against the real ~/Epicenter until the person asks.
Use a temporary home and a committed source. new --from copies code and
creates empty sibling data/; then build it as serve would. Uncommitted edits
are not copied. To test them, commit in a disposable copy outside the live
Epicenter, without changing the live branch or index.
bun test ./epicenter.test.ts # from code/: actions over memory
source_path=/absolute/path/to/source # choose a repository or subfolder
test_home=$(mktemp -d)
printf '[user]\n\tname = Test\n\temail = test@example.com\n' > "$test_home/.gitconfig"
HOME="$test_home" epicenter init "$test_home/Epicenter"
cd "$test_home/Epicenter"
HOME="$test_home" epicenter new example --from "$source_path"
HOME="$test_home" epicenter build example
HOME="$test_home" epicenter example --help
HOME="$test_home" epicenter serve --port 4799 # drive /example/ in this test homeIn the monorepo, the source CLI is bun <repo>/packages/cli/src/bin.ts.
The temporary Git configuration isolates identity and signing settings.
Run bun run typecheck and action tests from code/, where package.json lives.
Run tests one file or package at a time.
Only when the person asks, on the computer that runs epicenter serve:
epicenter new <app> --from <path|url>[#folder] takes committed code into
apps//code/ and creates empty data/. It installs but does not build;
run epicenter build <app> to check it before opening its page.epicenter init --from, then recreate local credentials.epicenter build [<app>] rebuilds from code/ui/ while retaining the last
good build. The project's own build script may empty its output first.A running serve loads edited code on the next call and checks code/ui/ on a page load. It serves code/ui/dist/ and keeps the last good build while rebuilding.
EpicenterHQ/epicenter
04f87cb
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.