Revetly 0.8.0 — the manual

The pages below describe this release, and travel with it. They are also inside the engine image: once it is loaded,

revetly manual list                     what is here
revetly manual show <page>              read one, offline
revetly manual export --into <dir>      copy them into your own project

None of that reads a network or calls a provider. Where the engine runs as a compose service, each is typed through it — docker compose exec revetly revetly manual list, from the instance folder — and Run a revetly command says so once for every page here.

Before you run it

what this licence lets you do, and where production use begins

• What you may do with Revetly — where production use begins, what a licence key is for, and when a release converts — read it before you run this on real work

Getting something done

one goal to a page, in numbered steps — the first-hour tutorial, and then a guide for each move somebody makes between downloading this and shipping a story from CONTEXT

• How-to guides — the guides, ordered along the journey a newcomer takes — and the shape every one of them holds to: what a guide is, what it may quote, and how each one is proven
• Your first hour — one path with no choices, from the download to a search that answers — read it before any of the guides, and read nothing else while you are on it
• Install Revetly from the handout and start the stack — from a folder of tarballs to a doctor that runs: which file is yours, what to check it against, and the one failure a fresh instance always reports
• Run a revetly command — what to type where the engine is a compose service: the command through the service from the instance folder, the same command by container name from anywhere, and the compose file to name when init left a second one
• Create an instance with revetly init — scaffolding the declaration, the compose file and the working agreement into a folder — as an installed command, from the image, and on a re-run that adds the update endpoint
• Give an instance a provider key and confirm it — answering the one failure a fresh instance reports, on the page or in the file beside the declaration, and reading the verdict back offline
• Run an instance with no provider key — declaring no provider on both sinks — on the page and in the file — and what a lite instance then prints, prices and answers
• Add your first project from the page — naming a project and pointing it at the folder it reads, through the configuration page rather than the file
• Price and run the first pass, and know it landed — the two commands that price a pass before it is paid for, the one that runs it, and the three readings that say whether what it wrote is there
• Connect a documents folder — adding a folder of prose to what one project reads, through the configuration page, and checking that Revetly can reach it
• Connect private git repositories with one credential — one [git.credentials] table, the variable its token is read from, and what the doctor says at each stage
• Connect a Todoist project — the board this project reads, the variable its API token is read from, and what the check says before that token is there
• Connect an Azure DevOps team project — the organization and the team project this instance reads, the variable its access token is read from, and what the check says before that token is there
• Connect a GitHub repository — the one repository this instance reads, the variable its fine-grained personal access token is read from, and what the check says before that token is there
• Write approved stories to GitHub — the store an approved draft lands in, the token permission it needs, the labels that must already exist, and what the doctor and the rehearsal say before a write
• Move a backlog to GitHub — the ordered plan a migration prints, the decision one apply needs, how a rerun resumes, and the discard each old file is flipped to
• Connect Claude Code in the terminal — the file init wrote, the tools that connection is served, and the dialog a review renders as in the terminal client
• Connect the Claude desktop app — the custom connector the app adds over HTTP, the host its registration needs declared, and the panel a review renders as
• Reach a hosted instance over HTTP with sign-in — the endpoint on an address other people reach, the declaration it refuses to start without, and what one real token resolves to
• Add a teammate to a hosted instance — one path from an instance only you reach to a teammate reading it — sign-in declared, the public address, the registration allowlist doctor names, and their first read
• Ground a topic before you write — asking CONTEXT what it already holds before the chat answers for it — the stated half before the inferred one, and a gap named rather than filled
• Draft a story and put it up for review — writing an ask down with what informed it cited, and handing it to the human who accepts or rejects it in the chat
• Capture a discussion — keeping the reasoning of a discussion while it is still in the room, with each decision in it named and linked
• Record a decision — one call written down as its own note, with the reason that forced it and the alternatives that were weighed and not taken
• Ship a story with a verdict per criterion — marking a story done with evidence and one verdict per acceptance criterion, which writes the delivery record beside it
• Run watch unattended — putting the reading loop on a clock — what the interval declares, one tick run by hand, and the loop left running in the engine service
• Read history from before the connection date — what each source declares it can reach back to, what reading it would cost, and the ceiling one paid run is held under
• Update to a later engine — the host-side swap: what a release publishes, whether it can read the corpus already here, and the pin the compose file carries
• Add a second project and say what may cross — a second body of work beside the first: its own namespace, its own root, and the exports and imports that decide what either can read of the other
• Reuse one connection across projects — one credential and address stated at instance level, and the question every project's Add source then asks: whose connection this source runs on
• Override a setting for one project — one project's own answer written beside the instance's — the five sections open to it, editing one in place, and taking it back
• Snapshot before a move — the local, free copy of a project's graph and ledger taken before a host moves — what it holds, and the gesture that replays it
• Move an instance — an instance is one folder and the state beneath it — what has to travel, what names the new root, and the chain that says it arrived whole

Setting it up

every input the engine reads, and how one instance holds several projects

• Engine config surface — every runtime input the engine reads, and what each one decides — and, at the top, the page they are set from: four levels, what it asks for first, and what it will not name
• The words this engine uses — the glossary every label, summary, page, fix line and tool description is written in, the rules each is held to and how far each rule reaches — read it before you name a setting or write a page
• The configuration page's vocabulary moved — a pointer: the standard this page held is now the house standard, at writing.md
• Reaching a private repository — how the engine authenticates to a git remote, where the token goes and where it may never go — read it the first time a source stays stale and doctor says a remote could not be reached
• Several projects in one instance — declaring more than one project, what may cross between them, the shared namespace — and what grade of isolation this actually is; read it before you put a client engagement beside your own repos

Extending it

reading a source Revetly ships no connector for, writing back to a store, and driving the engine from a client of your own

• Connector contract — what every connector reads, what each field mints, and the artifact envelope — read it before an import or a connector
• Writing a connector — how to read a source Revetly does not ship a connector for
• Writing a write adapter — the other half of a backend: landing an approved story in a store
• Driving the engine from your own client — every MCP tool the engine serves, which of them write, and what a client must render for the human review gate to work at all

Running it

adopting a project's history, what a failed pass and a stale corpus mean, and updating an instance in place

• Adopting a project with the history it already has — what history your sources declare, what reading it would cost, and what a corpus that was read back only so far will and will not answer — read it on the day you point Revetly at a live project
• When the provider says no, and when CONTEXT is behind — which provider failures retry, what a stale corpus means, and what the corpus revision refuses — read it when an ingest fails
• Which provider, and where every body goes — how [llm] and [embedding] declare the vendor, the endpoint and the models bodies leave for, what each of the five shipped providers pins and which of them can say what it runs, why an Anthropic instance embeds through a second vendor, what a compatible endpoint must serve, the endpoint rule the engine refuses to start against, and how to register one of your own — read it before you point this instance at a key that is not OpenAI's
• When the ledger and the graph disagree, and how the corpus comes back — how a pass checks that the graph still holds what the ledger says was sent, what divergent means, and how to snapshot, restore or rebuild a corpus without paying the provider again — read it before you move a host, prune a volume or lose a ledger
• What extraction is allowed to do to each kind, and to name — which kinds a model reads and which the engine only indexes, what an indexed artifact keeps and loses, what declared refuses to extract and how the pass folds and withdraws what the corpus already holds — read it before you connect a repository with a long history, and when search comes back full of paths and version strings
• Scoring what extraction writes — a seeded corpus whose answers are known, sent through this instance's model and scored — what each number measures, what it costs, and what it does and does not prove; read it before you change the model or raise the graphiti-core cap
• Serving people who are not you — what any OIDC issuer has to satisfy for this engine to trust it, the kit that satisfies it if you have none, the grant table that says who may read what, the token a machine presents, the revocation window a short access token implies, and what a front end has to satisfy when the address clients reach is not the one this engine binds — read it before anybody but you reaches this instance
• Updating an instance without a shell — the update endpoint: what it serves, what it refuses, what a job records — read it before you point a UI at this instance