Syncing

How the architecture in Kimtu gets there, how it is replaced, and what is not automated yet.

In a workspace

A team workspace keeps its repositories between visits. Each one is connected once (in the app, or with kimtu repo create), then synced whenever you like by running its prompt again in your own coding agent, or kimtu sync yourself. Nothing is pulled: Kimtu has no access to your repository.

Synced as you: The prompt runs kimtu sync, signed in to the kimtu CLI as you, so it holds no secret and the repository's page can show it again at any time. If the CLI is not installed or signed in, the agent stops and says to run npm install -g @kimtu/cli and kimtu login.
One request: A sync uploads kimtu.yaml and, if you opted in, the markdown and mkdocs.yml in a single request, so two runs syncing one repository cannot mix their files. The manifest's repository.id must be the repository's.
Tokens are for CI: A CI job has nobody to sign in, so it uploads with a repository token instead, issued from the repository's page: kimtu_rt_ followed by 256 random bits, shown once, for that repository alone. It never expires and can be revoked.
Replaces its own repository: An accepted upload replaces that repository's manifest and documentation and nothing else, and the workspace's map is recomputed from every repository's latest.
Judged by its own file: An upload is rejected only for problems in its own repository's files. A conflict with another repository — the same component declared twice, an external described differently — never blocks it; it appears as a workspace issue for every member.
What each repository shows: When it last synced and the commit the agent sent, and a log of every attempt with its issue codes. Nothing is marked stale: Kimtu cannot tell what current means for somebody else's repository.

How a demo import happens

You open a workspace, copy the prompt it gives you, and run it in your own coding agent. The agent reads the repository on your machine, writes kimtu.yaml, and uploads that file — plus the markdown under the documentation directory and mkdocs.yml, if you ticked the box. Nothing is pulled: Kimtu has no access to your repository and holds no credential for it.

Importing again into the same workspace replaces the architecture with the new file. Documentation is staged first and attached when the manifest validates, so a page appears only once an import has accepted it, and a file rewritten afterwards shows its new text — the last write wins.

A workspace is a demo session addressed by its id. Its upload token is shown once, and it stops accepting uploads an hour after it is created.

Import your own repositoryOpen a workspace and copy the prompt

Scheduled syncing Not shipped yet

There is no GitHub Action, no scheduled job and no webhook. Nothing re-reads your repository on its own. A CI job can upload with a repository token, and the repository's page gives the step to run, but Kimtu provides no Action or schedule of its own. Keeping a workspace current otherwise means syncing again.

Early MVPThis is the first integration approach. We are building toward making architecture and product knowledge available to your development tools and AI agents without this manual import step.

Available now: A one-shot import: your coding agent writes the configuration and uploads it to a workspace you opened.
In progress: Continuous integration with the development workflow, so the map updates as the system changes rather than on a manual import.
Planned: Direct agent access to the knowledge layer, so an agent working in your repository can query architecture and product context as it works.

What a page tells you about its source

A documentation page carries the path it came from, and the commit and date of that file's last change when the agent sent them — it reads both from git log, so they are there when the repository is a checkout and absent when it is not. The time is when the file last changed, not when it was uploaded.

There is no staleness mark. Nothing compares a workspace against your repository, so nothing can tell you it has fallen behind — if that matters to you, the commit on the page is the thing to read.

Removals and renames

Nothing is diffed. An import replaces what was there, so a component missing from the new file is simply gone — there is no redirect, no tombstone and no record that it used to exist.

A renamed id: The id is the identity, and it is in the URL, so renaming one produces a different component with a different page. Nothing follows the old id, and no field records what it used to be.
A renamed name: Changes the display everywhere and nothing else. The id it is keyed by has not moved.
A changed set of ids: Can move other components' colours. Hue is assigned by position in id order, not declared, so adding or removing a component reshuffles the ones after it.
A failed import: Writes nothing. The response names every problem at once — each with its code, its message and a pointer to the line, like components[0].relationships[1].to — and the architecture you had is untouched. A workspace's repository keeps a log of its attempts, with their issue codes.