← Documentation

Keep a page for your team

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.

  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 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).

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.

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 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);
  • 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).

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.

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.