On this page
  1. Summary
  2. Motivation
  3. Goals and non-goals
  4. Prior art
  5. Proposal
  6. Alternatives considered
  7. Compatibility and migration
  8. Security and privacy
  9. Drawbacks and risks
  10. Verification
  11. Open questions
  12. Implementation

Summary

Organize cotty’s documents as state documents and event documents, joined by a fold rule. Record technical decisions as thin RFCs. Publish every page in English and Chinese. Build the site with Hugo, with templates and check scripts owned by the project and no dependency on the JavaScript package ecosystem.

Motivation

cotty is designed before it is built, and design means both product design and technical design. Its protocols are meant to be implemented by other terminals and other agents, so other people will work from these documents. The documents are part of the product.

Three needs follow:

  • Product design will grow version by version. At any moment there must still be one complete description of the current design, for product and for technology.
  • Technical decisions need a dated record that others can read.
  • Research needs a place, with its date and sources.

Before this RFC there were five notes in one folder. They mixed dated findings with claims meant to stay current, and nothing marked which was which. If nothing is done, decisions stay in chat transcripts and the notes go stale without anyone noticing.

Goals and non-goals

Goals:

  • One complete, current description of the product design and of the technical design at all times.
  • A dated record of each technical decision, with its reasoning and the alternatives rejected.
  • A home for research, dated and sourced.
  • A site in English and Chinese.
  • Rules checked by a program wherever a program can check them.
  • A build chain small enough to audit.

Non-goals:

  • A user manual. There is no product yet.
  • A copy of the site per release. The version history is the snapshot until that stops being enough.
  • A process for outside contributors.

Prior art

Two research notes hold the evidence:

In short: projects that fold accepted proposals into a living specification stay readable, and projects that only append do not. The depth worth copying is in living documents, not in proposals.

Proposal

  1. Two kinds of document. A state document describes the present and exists once. An event document is dated and append-only.
  2. Fold. An event document says why something changes. The change is made in the state documents in the same commit.
  3. Thin RFCs. An RFC holds the decision and the reasoning. The normative text lives only in the state documents the RFC changes.
  4. The directory decides the kind. Product design, version designs, architecture, specifications, RFCs, research, posts and the handbook each have a folder.
  5. Two languages. Every page exists in English and Chinese at the same path, changed in the same commit. English is normative.
  6. A small build chain. Hugo as one pinned program, templates and a search script written for this project, pages that load nothing from other hosts, and checks written with the Python standard library.
  7. Publication. GitHub Pages publishes the site at https://nowa.im/cotty/. Every kind of document is published, research included.

The normative text is in Documentation system, RFC process and Templates.

Alternatives considered

  • One numbered stream for everything. Oxide and Earendil put decisions, investigations and principles in one series. The process is simple. But research is never accepted, it only has a date, and product increments come as bundles per version. Separate kinds let each have its own lifecycle and its own checks.
  • Thick RFCs that carry the full specification text. Rust and MCP do this. A reviewer reads one document. After acceptance the text is copied into the specification, and two copies drift. With thin RFCs there is one copy.
  • Chinese as the normative language, or one language only. The people who will implement the protocols read English, so English must be exact. Design discussion happens in Chinese, so the Chinese version is what gets reviewed first. Both are needed.
  • Translations as neighboring files, page.md and page.zh.md. The two versions sit together. But links then differ between languages, and the English tree is no longer clean. With one folder per language the links are identical.
  • Generators from the JavaScript ecosystem. Starlight, Docusaurus and VitePress were tested. Starlight fit best by function. Each brings 250 to 1200 packages into the build. That supply chain is too large for a project whose users trust it with their secrets.
  • Sphinx. Its translation mechanism stores the Chinese text as catalog files cut by paragraph, which cannot be reviewed as pages. This was not tested.
  • A third-party Hugo theme. Hextra was tested and worked. It is one more dependency to audit: it bundles libraries for search and diagrams, and it depends on one maintainer. The templates this project needs are a few hundred lines.
  • No third-party code on the pages. Diagrams would then be plain text or hand-made SVG. Repository browsers already draw mermaid, and architecture pages need diagrams. So one exception is made: a copy of mermaid, kept in the repository and loaded only on pages that have a diagram.
  • A last-changed date in the metadata. Nobody keeps it correct by hand. The version history already knows it.

Compatibility and migration

The five existing notes move as follows.

Before After
docs/01-terminal-essence.md posts/what-a-terminal-is.md and research/studies/2026-11-terminal-emulators.md
docs/02-landscape.md research/landscape/2026-11-agent-terminals.md
docs/03-strategy.md product/positioning.md and product/capabilities.md
docs/04-attention-cards.md product/attention-cards.md
docs/05-field-notes.md research/field-notes/2026-11-remote-spark-operations.md

The account in 03-strategy.md of how the thinking changed is not kept as history. Its argument stays in the positioning page as the reason for building both halves.

Security and privacy

  • The build needs one pinned program and the Python standard library. No package manager installs anything.
  • The pages load nothing from other hosts. The search script is written in this project. One third-party library, mermaid, is kept as a copy whose origin is recorded in site/VENDORED.md. JavaScript as such is not excluded. What is excluded is code installed through a package manager.
  • Research is published. The field notes use aliases in place of the names of internal machines, and hold no addresses and no secrets.

Drawbacks and risks

  • Two languages double the writing. A program can check that the two versions have the same structure. It cannot check that they say the same thing.
  • The templates and the search script are ours to maintain.
  • _index.md is a name that only Hugo requires.
  • Published pages refer to research notes that readers of the site cannot open.
  • The copy of mermaid is a large bundle. Its origin was verified, but it was not read line by line.
  • Reviewing a thin RFC means reading the RFC and the pages it changes.
  • The fold rule is checked only by its traces: the page lists and the RFC numbers. Whether the change was really made is a matter of review.

Verification

make check runs the source checks and make verify adds the checks on the built site. Each check was tried by introducing the error it should catch: a page missing in one language, a status that differs between languages, an invalid status, a link to a missing file, a link to a missing anchor, a level-one heading in a body, an accepted RFC whose affected page does not list it, and a page that loads a script from another host.

Open questions

One question is deferred. It does not block the decision.

  1. License of the documents. Deferred to the decision on the project’s license.

Implementation

  1. Create the folders and the handbook pages.
  2. Move the five notes and add their English versions.
  3. Write tools/check.py.
  4. Write the site configuration, the templates and the search.
  5. Build, and try each check against a deliberate error.
  6. Publish the site, and run the checks on every push.

Read first: Documentation system.