# Keep a page for your team

> Save a page and the files it needs from a Claude or Codex session with one word, find it in the Documents row of the app, update it, copy the commands that make an artifact or a post from it, and read it from a terminal.

*You made a page in a Claude Code or Codex session — a plan, a design, a
report. Say "keep this", and Zeus Mode saves the page and every file it needs
as one **document**. Everyone on your team sees it in the app, and can open
it whole. From its card you can update it, turn it into a Claude artifact, or
start a blog post from it.*

*Checked on 17 November 2026, on macOS 27.0.1. Zeus Mode 0.41.0 keeps,
shows and reads documents, and has the commands to copy and Make a post.
The parts marked **(next release)** — a page kept for a plan, and Update —
come in the release after 0.41.0; they were checked on a build of that work. The
`zeus doc` commands below were run on that build, in a test workspace whose
GitHub repository was a folder on the Mac. The session steps were checked
against Zeus Mode's skills and a try of saving in Claude Code, not run again
here. The app steps were checked against the app's source.*

## What a document is

A **document** is a page and the files it needs, kept together as one item:

- the **page** a person opens, such as `plan.html`;
- the files the page loads — its pictures, its styles, its scripts;
- if you want, the files that build the page again, and notes about it.

Zeus Mode keeps each document in its own folder, with a small file named
`doc.toml` that says what every file is. We call that file the **list file**.
You never write it: the session works it out for you.

Documents belong to a **workspace**: a named group of repositories that you
choose in the picker at the top of the rail (the list down the left side of
the Zeus Mode window). Everyone who works in those repositories sees the same
documents.

## Before you start

Zeus Mode keeps the documents in a private repository on GitHub that belongs
to the workspace. Zeus Mode calls it the workspace's **instructions home**. It
is the same repository that holds your team's todo list and the `ZEUS.md` file
Zeus Mode gives to every session. Each document is a folder under
`documents/` there.

You need three things:

1. **Zeus Mode, new enough to keep documents.** To check, run:

   ```
   zeus doc --help
   ```

   Its first line starts with `zeus doc — the workspace's documents`. If it
   says `zeus: unknown command "doc"`, your Zeus Mode is older than documents: see
   [Keep Zeus Mode up to date](/docs/getting-started/#keep-zeus-mode-up-to-date).
2. **An instructions home for the workspace.** If your team already keeps a
   todo list, you have one. If not, `zeus doc list` tells you, with the
   command that makes one:

   ```
   zeus doc list: Try Team has no instructions home yet, so it keeps no documents. `zeus workspace home create 'Try Team'` makes one.
   ```

   You can copy that command as it is. (Zeus Mode 0.41.0 prints the name
   without the quotes. If the name has a space, add them yourself:
   `zeus workspace home create 'Try Team'`.)
   [Your team's todo list](/docs/team-list/#before-you-start) says more about
   this repository and who can give you access to it.
3. **Write access to the instructions home on GitHub**, to save. To see the
   team's documents, read access is enough.

The page you keep must be in a repository on GitHub, and its files must be
committed. Zeus Mode records which repository and which commit the page came
from, so a teammate can find the original.

## Keep a page from a session

In a Claude Code or Codex session, ask for it in plain words:

```
keep this
```

or name the page: `keep docs/kit/kit.html`. You can also start Zeus Mode's
`/zeus-doc` skill by its name. In Claude Code, Zeus Mode's skills carry the
`zeus-protocol:` prefix, so you type:

```
/zeus-protocol:zeus-doc docs/kit/kit.html
```

Only your words save a document. An agent may say that a page looks worth
keeping, but it does not save it on its own.

### What the session tells you first

The session reads the page, finds every file it loads, and asks Zeus Mode to
check the group. It writes nothing yet. Then it tells you, in plain words:

- the document's **title** and **type** (plan, design, report, and so on);
- **opens first**: the page a teammate sees when they open it;
- **the files it needs**, by what each one is for;
- any file that is **missing** — the page loads it, but it does not exist — and
  any file **left outside** on purpose, each with its reason;
- **the ways to keep it** (see the next section), each marked as working or
  not;
- **where it will be kept**: your workspace's instructions home;
- **the plan it is for**, when the session is working on a step of a plan
  (see [A page kept for a plan](#a-page-kept-for-a-plan)).

In the try on Claude Code, the answer began like this:

```
I've checked the page and its files with Zeus. Nothing has been saved yet.

**Acme button kit**: type `design-system`, written by vikgup

**Opens first:** `kit.html`
```

and ended by asking:

```
Do you want me to keep it? If so, say which form (snapshot or rebuildable), and name it in your reply, for example "keep Acme button kit as a snapshot". Zeus only saves on words that name the document.
```

A secret file — such as `.env`, a key or certificate file, or a credentials
file — is never copied. Zeus Mode refuses it. The session leaves it outside
the document and tells you.

### Snapshot or rebuildable

- **Snapshot** keeps the files as they are now. It always works.
- **Rebuildable** also keeps the command that builds the page again, and the
  files that command needs. The session offers it only when the page has such
  a command, and only after it tried the command in a scratch folder. If the
  try failed, the offer says **will not work**, with the first error line.

If you are not sure, choose snapshot.

### Say yes, with the document's name

Answer with words that name the document, by its title:

```
yes, keep Acme button kit as a snapshot
```

Zeus Mode saves only when your words name the document. If your first
request did not name it, a plain "yes" is not enough: the save is refused,
and the session asks you to say the title.

The session then tells you what Zeus Mode answered: the document's name, the
GitHub repository it is kept in, the commit, the number of files, and the
plan it is for, if there is one.

**No pull request.** Zeus Mode writes the document to the instructions home
itself, as one commit. Nobody needs to review or merge anything.

### A page kept for a plan

**(next release)** When the session is working on a step of a plan, a page
you keep there is kept **for that plan**. Before it saves, the session tells
you so with Zeus Mode's own line, for example:

```
For plan: P-47 · One document store a team shares in Zeus — this session holds its step guide-commands (T-2653).
```

If the page is not for that plan, say so ("it is not for that plan"). The
session then saves it with no plan, and Zeus Mode says
`For plan: none — the person said it is not for a plan.`

A session that holds no plan step says
`For plan: none — this session holds no plan step.`, and the page is kept
with no plan. So does a session that holds steps of two plans or more: Zeus
Mode cannot tell which plan the page is for, and says so.

A page kept for a plan:

- names the plan on its card: **For plan P-47 · One document store a team
  shares in Zeus**. On the Mac that keeps the plan, those words are a link
  to the plan's page. On any other Mac, such as a teammate's, the card also
  says whose plan it is, with no link:
  `vikgup's P-47 · One document store a team shares in Zeus`;
- is listed under **Documents** on the plan's page.

To tag a page you kept earlier, or to take the tag off, see
[Tag a document with a plan](#tag-a-document-with-a-plan).

## Find it in the app

Open Zeus Mode and choose the workspace in the picker. The rail has a
**Documents** row, after **Explorations**. Its number is how many documents
the workspace keeps.

A document you or a teammate saves shows here **within about a minute**: Zeus
Mode fetches the team's documents once a minute. This holds on a Mac that
already uses the workspace's instructions home; a teammate setting up for the
first time follows [Your team's todo list](/docs/team-list/#every-other-teammate-nothing-to-run)
first.

**Documents** opens a page with one row per document, the newest change
first. Each row shows the title, then the type, who saved it, the repository
it came from, and how long ago. A row may also say `1 file missing`, when a
file the page loads is not in the copy on your Mac. A post that someone is still
writing says **in progress** before its title.

When the workspace keeps no documents yet, the page says:

```
No documents yet. Say "keep this" on a page in a Claude or Codex session.
```

Choose a row to open its details on the right:

- its type and form, such as `design · snapshot`, and its title;
- **saved by** who, and when, and **written by** which agent, when the
  session could tell;
- **from** the repository, the folder and the commit it was saved from;
- **For plan**, and the plan, when the page was kept for one (next release);
- **Open ↗**, which opens the page in your Mac's web browser, and, on a kept
  document, **Make a post from this document** (see
  [Make a post from this document](#make-a-post-from-this-document));
- a line about the original page, and **Update**, when it has changed (next
  release; see the next section);
- **Files**, with the page that opens first at the top, marked
  `page · opens first`;
- **Artifact**: the link of the Claude artifact made from it, and who can
  see it, or `None yet.`;
- **Commands to copy** (see [Commands to copy](#commands-to-copy)).

**Open** opens the copy on your own Mac, with all its pictures and styles.
It works without a network connection. If your Mac has no copy of the
document yet, **Open** cannot be pressed, and the drawer says
`This Mac has no copy yet.` Wait a minute for Zeus Mode to fetch it.

## When the original page changes: Update

**(next release)** Zeus Mode remembers the repository and the commit each
page was kept from. It compares the kept copy with the same files on that
repository's default branch (usually `main`), in the copy of the repository
on your Mac. It
does not download anything to compare: it uses that copy as it was last
fetched.

When a kept file has changed there since, the drawer says so, for example:

```
The source has moved on: 1 file changed since 2424a8e.
```

and shows an **Update** button, with the words
`replaces this copy; the store keeps the old one`.

Press **Update**. Zeus Mode copies the same files again, as they are on the
default branch now, and saves them as one new commit. It answers under the
button, for example:

```
Updated “Acme button kit” to 5c1e9a0; it replaced 2424a8e.
```

Here `5c1e9a0` is the commit on the repository's default branch that the
copy now matches, and `2424a8e` the one it matched before. The drawer then
shows `Replaced 2424a8e`. The old version stays in the
instructions home's history.

Update keeps the same list of files. A file added to the folder since is not
taken, and if the page now loads a new file, or a kept file is gone from the
default branch, Update changes nothing and asks you to save the page again from
a session.

Zeus Mode cannot always compare. The drawer then says why, for example:

- `This Mac has no copy of github.com/acme/server to compare.` — Zeus Mode
  looks only in the repositories it knows on this Mac: clone that repository
  and add it to the workspace;
- `This Mac's copy of github.com/acme/server does not have 2424a8e yet, so Zeus cannot compare.`
  — fetch that repository;
- `2424a8e is not on the default branch of github.com/acme/server yet, so Zeus cannot compare.`
  — the page was kept from a branch that is not merged yet.

A post (see below) has no **Update**: its words are written in the store.

## Commands to copy

Zeus Mode does not start a session for you. Instead, the
drawer has a part named **Commands to copy**. Each button there puts one
whole command on your Mac's clipboard, and the button says `Copied` for two
seconds. Paste the command into a terminal and press Return: it starts
Claude Code with the request already written. The drawer says it too:
`Run it in your own Claude session. Zeus starts nothing.`

Each command is one line that starts with `claude` and carries the
document's name and your workspace. For example, **Copy: make artifact** on
the Acme button kit copies:

```
claude 'Make a Claude artifact from the Zeus document acme-button-kit of the workspace Try Team: use the zeus-protocol:doc-artifact skill (zeus doc artifact acme-button-kit --workspace ws:try).'
```

Near the end, `ws:try` is your workspace's own key. Zeus Mode fills it in;
you do not need to change anything in the line.

### Copy: make artifact

On every document. Run it in a terminal in any repository of the workspace.
The session:

1. copies the document out of the store into a folder of its own;
2. changes a **copy** of the page so it follows the rules of a Claude
   artifact (a short title, colours that follow dark mode, the artifact's
   side margins), and puts the page's styles and pictures inside it. If the
   document has files the page does not load, it adds a short part at the
   end, "Files in this group", that lists them. It never changes the page's
   words, and never changes the kept page;
3. publishes it as a Claude artifact. A new artifact is **private**: only you
   can see it;
4. records the artifact's link, and who can see it, on the document.

Within about a minute, every teammate's drawer shows the link under
**Artifact**, for example `private · published by vikgup`. Who can see an
artifact is changed on claude.ai, never by Zeus Mode.

Making an artifact needs Claude Code signed in to claude.ai. A session that
cannot publish one says so and stops.

### Make a post from this document

On a kept document (not on a post), there is a button named **Make a post
from this document**, beside **Open ↗**. It does not copy anything: Zeus Mode makes the
post at once, in the same store, and opens its card.

A **post** is a blog post in progress. It is a document of its own, with an
empty `post.md` to write in. Its title is the document's title followed by
` — post`, such as `Acme button kit — post`, and its card says
**Made from** and the document's title. In the list it says **in progress**
before its title.

### Copy: continue editing

On a post. Run it in a terminal in any repository of the workspace. The
session opens the post's one working copy on your Mac, and you write or
change the post with it, in your own words. When you say you are done, it
saves the post for the whole team, as one commit. Every teammate's card
shows the new draft within about a minute.

The app has no editor of its own: you always edit a post in a session. On a
post, the drawer says
`Run it in your own Claude session. Zeus starts nothing, and the app has no editor.`

If a teammate saved the same post while you were editing, nothing is lost.
The session merges their changes into yours, shows you any lines you both
changed so you can choose, and saves again.

### Copy: publish this post

On a post. Run it in a terminal in **your site's repository** — the
repository your blog is built from. The session copies the post out and hands
it to that repository's own skill for writing posts. That skill turns the post
into the site's layout and opens a pull request. Zeus Mode itself never
changes your site.

Under the button, the drawer says:

```
Publish opens a pull request in the site's repository. Nothing is published until it is merged.
```

Once the pull request is merged and the post is live, its live link is
written on the post, and the post is kept from then on. The site's writing
skill may write the link itself. If it does not, the session gives you one
line to run when the post is live:

```
zeus doc live acme-button-kit-post --url https://example.com/blog/acme-button-kit/ --words "Publish the Zeus post acme-button-kit-post"
```

Use your post's name and its live address.

A post also has **Copy: make artifact**, shown with quieter words, under the
other two.

## Use it from a terminal

The same store has a command, `zeus doc`. Run it inside a repository of the
workspace. If that repository is in more than one workspace, add
`--workspace <name>`.

### See what your team keeps

```
zeus doc list
```

It prints every document, with who saved it, when, and from where:

```
The documents kept in github.com/acme/zeus-instructions:

acme-button-kit · Acme button kit · kept, design
  saved by <your name> on 17 Nov 2026 09:03, from github.com/acme/server
```

In place of `<your name>`, it prints the name Zeus Mode knows you by. The
first word on each line, `acme-button-kit`, is the document's **name**.
Zeus Mode makes it from the title. With no documents yet, it prints
`github.com/acme/zeus-instructions keeps no documents yet.`

### Check, then save

This example uses a smaller kit than the session example above: one page,
one style file and one picture.

The session usually does this for you. To do it yourself, first ask Zeus Mode
what a save would keep. `check` writes nothing:

```
zeus doc check docs/kit --title "Acme button kit" --open kit.html --type design --member kit.html=page --member kit.css=asset --member img/button.svg=asset
```

- `docs/kit` is the folder that holds the page and its files.
- `--open` is the page that opens first.
- `--member <file>=<role>` names each file, one `--member` for each. The role
  is `page`, `asset` (needed to show the page), `source` (needed to build it
  again), `note` or `licence`.

It answers with where the document would be kept, where it comes from, each
file, and each file the page points at. If you forgot a file the page loads,
it says so, and says that Zeus Mode would refuse the save:

```
Zeus would refuse it now:
  kit.html points at img/button.svg, which is neither a member nor written under outside.
Nothing was written.
```

Add the file as a member, or, if you mean to leave it out, write it with
`--outside "<file>=left_outside:<reason>"`. When the group is right, it ends:

```
Zeus would keep it as it is: a save with the person's words writes it.
Nothing was written.
```

Then save with the same flags, and your own words, which must name the
document:

```
zeus doc save docs/kit --words "yes, keep the Acme button kit" --title "Acme button kit" --open kit.html --type design --member kit.html=page --member kit.css=asset --member img/button.svg=asset
```

It answers:

```
Saved acme-button-kit in github.com/acme/zeus-instructions, commit a2bf97c8aa5ef12e533527d9896a7148f3c71c66: 3 files, opening kit.html. For plan: none — this session holds no plan step.
```

Zeus Mode 0.41.0 ends the line after `opening kit.html.`; the `For plan:`
part comes in the next release, and `check` says it too.

`zeus doc --help` lists every flag, such as `--form rebuildable` with
`--build "<command>"` for a document that can be built again, and
`--plan none` for a page that is not for the plan the session works on.

### Tag a document with a plan

**(next release)** To say that a document you kept earlier is for a plan of
yours, name the document and the plan:

```
zeus doc plan acme-button-kit P-47 --words "tag the Acme button kit with P-47"
```

It answers `Tagged acme-button-kit with P-47 · <the plan's title> in github.com/acme/zeus-instructions, commit …`.
The plan must be one this Mac keeps. If it is not, Zeus Mode says
`This Mac's work store has no plan P-47, so Zeus cannot tag a document with it; nothing changed.`

To take the tag off, write `--none` in place of the plan:

```
zeus doc plan acme-button-kit --none --words "take the plan off the Acme button kit"
```

### Read a document

```
zeus doc read acme-button-kit --words "read the Acme button kit"
```

It copies the document into a folder of its own on your Mac, and prints its
list file, the commit it read, and the path of each file — the page that
opens first comes first. Your words must name the document. If they do not,
nothing is read:

```
zeus doc read: The person's words do not name the document acme-button-kit ("Acme button kit"), so Zeus does not read it. Nothing was read.
```

## When an agent may read a document

Zeus Mode's rules tell an agent to read a kept document only when **you
point it at that one document**, for example "read the Acme button kit and
use its colours". It reads it through its `doc` tool, the same way as
`zeus doc read`, and the words it passes must name the document.

- Its `doc` tool has no way to list the store or to read every document in
  it. This is a rule for agents, not a lock: an agent that can run commands
  in a terminal can run `zeus doc list` like you. To keep a repository's
  agents away from another repository's documents, use the file in the next
  section.
- An agent does not save a document on its own. It may say that a page looks
  worth keeping; only your words keep it.
- A repository can refuse documents from another repository. Then the read
  is refused, for an agent and for you alike, with the reason (see the next
  section).

## Keep a repository from reading another's documents

Some teams have a rule that one repository must not use work from another —
for example, a "clean room" that must never see another product's code. You
can write that rule where Zeus Mode reads it. Add a file named
`.zeus/reads.toml` at the top of the repository that must not read, with one
`[[refuse]]` block for each rule:

```
[[refuse]]
source = "github.com/acme/server"
rule = "The web team keeps a clean room: no code or design from the server repository (CONTRIBUTING.md, Clean room)."
```

- `source` is the repository whose documents are refused, written
  `github.com/<owner>/<name>`. Write `"*"` to refuse documents from every
  repository except this one.
- `rule` is the rule in your own words, and where it is written. Zeus Mode
  shows it in the refusal.

The rule holds as soon as the file is there; commit it so it holds for
everyone who works in the repository. From then on, a read from this
repository of a document saved from that source is refused, for a person at the terminal and for an
agent alike:

```
zeus doc read: This repository's .zeus/reads.toml refuses documents from github.com/acme/server: "The web team keeps a clean room: no code or design from the server repository (CONTRIBUTING.md, Clean room).". Nothing was read.
```

Write the file carefully. If Zeus Mode cannot read it — a typing mistake, or
a rule with no `source` or no `rule` — it refuses every read from that
repository until you fix it, and says why, for example:

```
.zeus/reads.toml's rule 1 names no source, so Zeus refuses every read from this repository until it parses.
```
 A rule written only in a README or another
document is not read.

## When something goes wrong

**"The person's words do not name the document"** — the words of the save do
not contain the title or the name. Say it again with the title:
`keep Acme button kit`.

**"The store already keeps a document called …"** — a document of that name
exists. To replace it, tell the session to update it (`--update` on
`zeus doc save`); the instructions home's history keeps the old version. To
keep both, give the new one another title, or another name with `--name`.

**"These files are not committed as they are now"** — commit the page's files
in their repository first, then save again. Zeus Mode records a commit, and
that commit must hold the files it copies.

**".env is an environment file, so Zeus never copies it"** — a secret file
was named as part of the document. Leave it out; the session writes it as
left outside.

**"This repository is in 2 workspaces …, so name the one … with
--workspace"** — add `--workspace <name>` to the command.

**"… is not in a repository with a GitHub origin"** — the page must be in a
repository whose `origin` is on GitHub.

**"… has no instructions home yet"** — see step 2 of
[Before you start](#before-you-start).

**The Documents row does not show a document a teammate saved** — wait a
minute, then look again: Zeus Mode fetches the team's documents once a
minute. If the page says it could not fetch the instructions home, check that
your Mac can reach GitHub and that you have read access to that repository.
