Projects: what they keep

A project that iohr project init started keeps its record, its documents and what it has learned in the folder, next to the code, and sends its documents to its space in InOrbit. This page is what each part holds and how to keep it current.

Where the project keeps its dataCopy Anchor Link

In iohr-preview, init asks where to keep what iohr learns about the project: in the project folder (.inorbit/, so it travels with the repository) or in your home folder (~/.inorbit/projects/NAME/, so it stays on this machine). That covers the project's notes, what a crawl keeps and the project's state. The choice is written as [project] data in inorbit.toml.

iohr-preview project init my-shop --keep-in home
iohr-preview project init my-shop --keep-in project --copy-data

--keep-in (or IOHR_INIT_KEEP_IN) answers without asking. Nothing is moved unless you choose, and --copy-data copies what is already there, never deletes. With no choice recorded, a project keeps the layout older versions made: notes and crawl in the project, state in your home folder. atlas/, inorbit.toml and .inorbit/space always stay in the project.

The project's shapeCopy Anchor Link

Also in iohr-preview, init asks whether the project is a monolith, microservices or combined. The question is an item in the project's Planner plan. Answered at a terminal, the answer is written to [project] shape in inorbit.toml and ? knows it. Without a terminal, the item stays open for you to answer from the Mac app or the phone. --shape (or IOHR_INIT_SHAPE) answers it up front.

The record and the linkCopy Anchor Link

Two committed files tie the folder to InOrbit. Neither holds a secret.

• inorbit.toml at the root is the project's record: its name and id, its kind, the template it came from, and the links that stay empty until each exists (space_id, listing, memory_namespace).
• .inorbit/space names the space the project records to, as id, name and account. Init writes it when it makes the project in InOrbit, and iohr project sync writes it later. A link to a local stack goes in .inorbit/space.local instead, which git ignores.

Both files are committed, so a teammate who clones the repository has the same record and the same space link.

The atlasCopy Anchor Link

atlas/ is a plain folder you can read and edit: prd/, rfc/, adr/, studies/, canvas/, models/ and roles/. A document is Markdown with front matter that maps one to one onto a Decisions document.

$ iohr atlas new rfc "Cache the catalogue"
└  atlas/rfc/0002-cache-the-catalogue.md written (number 0002)

iohr atlas init adds the folder to a project that was made without it.

SyncCopy Anchor Link

iohr sync sends the atlas to the space named in .inorbit/space, through Decisions. It creates what is new, saves a new version of what changed, and when a document changed in Decisions since you read it, it says so and overwrites nothing. Ids and versions are written back into the front matter and stay local. The canvas and 3D folders are never sent.

iohr sync --dry-run    # what would be created or saved; sends nothing
iohr sync              # send it

With no space linked, it stops and says how to link one:

$ iohr sync
iohr: no Decisions space: give `--space ID`, or link the project with `/inorbit:link <space>`

Sync goes one way today: from the folder to Decisions. Nothing pulls documents back, and nothing syncs in the background; iohr sync is the only thing that sends documents.

MemoryCopy Anchor Link

iohr memory keeps what a project has learned as Markdown files with a reason and a source, so an agent can find it by topic instead of being told again.

$ iohr memory remember "We use sqlx" --why "typed SQL"
id      we-use-sqlx-for-typed-sql-313b4d
status  kept
scope   project
file    .inorbit/memory/we-use-sqlx-for-typed-sql-313b4d.md

iohr memory recall "database"      # ranked by word match, recency and pin
iohr memory list
iohr memory check                  # missing reasons, stale or dangling entries, gaps
iohr memory forget <id>

There are three scopes, picked with --scope: project (in the repository, the default inside one), user (yours, on this machine) and account (kept in InOrbit, off until you turn sync on). A text that looks like a secret is refused, and a memory is never written to a log.

RolesCopy Anchor Link

The built-in Roles are written to atlas/roles/: security for every project and one engineer for the project's language (rust-engineer, python-engineer, typescript-engineer or go-engineer), and base-engineer too when your account has none. Each has a short core and recall lines, with the primary source each line comes from.

Signed in, init sends them to your account as an import and says per Role what happened: written, upgraded, unchanged, or left alone because you changed your copy. iohr atlas roles import --upgrade is how you take the newer catalogue on purpose. Only an owner or admin of the account may import. Signed out, iohr sync or iohr atlas roles import does it later.

--role NAME adds a Role to the project. Init looks for it in the new project's atlas/roles/, then in your account, then in the built-in catalogue. The Roles also answer every ask in the project's session: see Answers from your Roles.

Teams, visibility and sharingCopy Anchor Link

The project lives in InOrbit under the account you chose with --team, seen by everyone in it or only its owners and admins (--visibility). That setting is who can see the project, not a list of members.

The folder is shared the way code is shared: through git. inorbit.toml, .inorbit/space, .inorbit/memory/ and atlas/ are committed. A teammate who clones the repository, signs in and runs iohr sync sends documents to the same space, with the access the space gives them.

What iohr does not do yet: a Keychain slot for the project's own token, a private listing in the Marketplace, a memory namespace of its own, and its own monitors and notifications channel. Sync does not pull documents back either (see Sync). Under --verbose, init reports each of these as not yet, with the thing it waits on, so you can see what is left rather than guess.