The scaffold is public, and holds nobody's records
The scaffold holds the commands, the templates and the onboarding material. It contains no organisation's content, so reading it tells you nothing about anyone's projects.
the second half of the pair
Project Hub
one private repository for an owner — and entirely optional
Everything you oversee, in one private repository.
Project Context installs in each project repository and belongs to the people building it. A Hub is the other side: one private repository where you author what applies everywhere, keep a folder per project, and read what the builders wrote — without ever handing them a permission on it.
- global/
- projects/<id>/
- owners_window/
- plain Markdown in Git — no service, no database
01 what you are looking at
The public repository is a template. Your Hub is not.
Two different things share the name, and mixing them up is the misreading everyone makes first. Read this bit before anything else.
A Hub is an instance you make from it
You copy the scaffold into a new private repository of your own, and that repository is your Hub. It is private, and it stays private. One Hub, one owner.
A Hub is closed to builders — by construction, not by policy
The people working in your project repositories hold no permission on your Hub — not write, not read. That is not a rule you have to enforce; it is what a private repository they were never invited to already does. It works on a free plan, where private repositories have no code owners, no protected branches and no required reviewers.
02 two products, one record model
Split by role, not by format
Both halves are small Markdown records in Git. What separates them is who they serve — the people doing the work, or the person who oversees several repositories at once.
| Product | Where it lives | Who it serves | Who can see it |
|---|---|---|---|
| Project Context | Installed in each project repository, versioned beside the work it describes. | The builders. The people doing the work own the record of the work. | Anyone with access to that repository. |
| Project Hub | One private repository of its own, administered by one person. | The owner — the person who oversees several repositories and writes what applies to all of them. | The owner. Builders hold no permission on it, not even read. |
one parser, one schema, one doctor
Both sides validate records with the same parser, the same schema and the same doctor — because a Hub is itself a Project Context install. The shared code arrives there by the ordinary create-only install rather than being vendored a second time, so there is no second record model to learn and no second thing to keep in step.
03 the direction of travel
Two directions, and the owner starts both
Content moves between the two repositories in exactly two directions. There is no third path, and no builder-initiated one.
private · one owner
Your Hub
- global/ authored here
- projects/<id>/blueprint/ authored here
- projects/<id>/pulled/ a stamped copy
- owners_window/ never leaves
Builders hold no permission here — not even read.
push
the global tier and that project's blueprint, onto a branch, as a pull request
pull
the repository's own authored records, copied up and stamped
one repository you oversee
A project repository
- project-context/global/ pushed · read-only
- project-context/blueprint/ pushed · read-only
- NOW.md · DECISIONS.md · QUESTIONS.md builder-authored
Everything outside the pushed set is theirs to write.
Both arrows are started by the owner, from the Hub, and only in the direction their access already allows.
push — Hub into a repository
global/ and that project's blueprint/ land in the repository's project-context/, stamped. It does not write to your default branch: it commits to a long-lived hub-sync branch and opens a pull request, so what an owner sends arrives as a change the repository reviews like any other. Repeated syncs stack commits on the same branch and update the same request rather than scattering branches. Nothing force-pushes, and nothing merges — merging stays with the repository.
pull — a repository into the Hub
The repository's authored records are copied up into projects/<id>/pulled/, stamped with repository, branch, commit and time. It is read-only against the repository — it reads the git object database and writes nothing there. This is also your inbox: a question or a proposal a builder raised arrives on this path, and nothing moves until you pull.
init — a repository the Hub does not know yet
It marks the repository, writes a first summary of it, installs Project Context into it, and then pushes — the install and the push sharing one branch and one confirmation. Refused outright when Project Context is already installed; that repository wants pull or push instead.
nothing calls home
Nothing in a project repository ever reaches out to a Hub. There is no call home, no registration, no credential. The direction is one way by construction: the owner has access to your repository because they administer it, and you have no access to theirs.
04 exposure, not convenience
Nothing travels that you did not name
A project repository may have collaborators who are not in your organisation. So the question a push answers is never what would be convenient to share — it is what someone outside the organisation may end up reading.
An allow-list, never a deny-list
A push copies only what the Hub's own configuration names, and nothing else. Any folder you add to the Hub later is non-pushed by default and needs no special case to stay put. The asymmetry is the whole point: forgetting to add a deny rule leaks, and forgetting to add an allow rule does not.
The shape of the list
Most of the global tier travels — the summary, the guardrails, the workflows, the shared records a builder works against, and that project's blueprint. A few of the more sensitive files are opt-in per project rather than default, because objectives across every project, internal dashboards and a roster of people are each more sensitive than the guardrails a builder actually needs. And one file never travels at all.
IDENTITY.md never reaches a project repository, at any setting. Identity is the organisation's own voice, and it does not belong committed into someone else's checkout. It is the one rule the configuration cannot relax: a Hub whose allow-list names it does not get to push it — the entry is dropped, and you are told which one was refused.
no transcripts, in either direction
Sessions stay on the machine they happened on. What travels is a short capsule — at most 200 words — and only when the builder chose to write one.
05 what you actually get
One place to write, one place to look
Four things. They are the whole product, and everything else in the scaffold is machinery for getting content into them and out again safely.
One place the global tier is authored
Identity, guardrails, workflows, goals, resources. You write them once, in global/, and push the shareable subset into the repositories that need it — instead of a near-copy per repository, quietly drifting apart.
A folder per project
Its mark — remote, default branch, visibility, who builds it — your own summary of it, and the blueprint you author for it: blueprint/EPIC.md, the goal the project serves, and blueprint/ARCHITECTURE.md, the shape it has to keep.
The builders' own records, brought to you
A pull copies each repository's plan, tasks, decisions, learnings and open questions into projects/<id>/pulled/. You read them here, side by side, without cloning anything. Do not edit that copy — the next pull overwrites it, and the record lives in the repository it came from.
A window of your own
owners_window/ is where you write about what is coming: half-formed projects, reflections, an argument with yourself. Never pushed, never linted, never pulled into. An idea leaves it only by being promoted by hand — into a blueprint, a global record, or a mark for a repository that does not exist yet. Freeform in, structured out.
06 optional, and that is the feature
A repository with no Hub is not a degraded one
global/
blueprint/
absent when there is no Hub — and nothing breaks
A repository with no Hub simply has no pushed set. Every Project Context feature still works, offline, with no network at all.
A Hub never appears on its own. It is created deliberately, by someone who wants the aggregate view — so the pair is two halves you can hold separately, and a single repository needs nothing but its own install.
07 on the receiving end
If you disagree with something pushed to you
Worth knowing on both sides of the pair: the builder needs a way to object, and the owner needs to know where objections arrive.
Do not edit it
The pushed set is read-only where it lands, and the marker holds each file's hash. The doctor flags the edit, and your next push refuses: one edited copy is a conflict that stops the whole push to that repository, naming the file and saying the place to change it is the Hub. So an edit does not quietly lose the argument — it blocks the sync while still telling you nothing about the objection.
Raise a question in your own record instead
File it in your own project-context/ — a question in QUESTIONS.md, or a proposal capsule in inbox/. Both belong to the authored set, so the owner's next pull brings them up alongside the project context that explains why. The owner changes the record at its source and pushes again.
the weak point, named
Nothing moves until the owner pulls. That is the honest cost of a Hub builders cannot reach — which is why pulling every repository has to be routine, and why the oldest unanswered question is the one to read first.
08 the cost, stated plainly
What a Hub costs, and what it buys
A guardrail change means touching every repository
Pushing to all of them is one command, but it is one branch and one pull request per repository, and each of those still has to be reviewed and merged by the people who own it. A repository nobody has pushed to lately goes stale — though the check reports how old each stamp is, so it does not go stale quietly.
What you buy with it
Builders hold no permission on the Hub — not even read — and a project repository needs no network at all to work. There is nothing to run, nothing to log into, and no dependency to install: it is plain Markdown in a Git repository, readable in any editor, on a machine with no agent on it.
licence · worth knowing first
MIT with the Commons Clause v1.0 condition. You may use, copy, modify and distribute it, including inside your own organisation; you may not sell it, or sell a service whose value is substantially this software. The Commons Clause makes it not an OSI-approved open source licence, which is worth knowing before you build on it.
09 getting started
Make one, then ask it to set itself up
The scaffold ships the agent that does the setup. It identifies your tool, asks you one round of questions, writes a thin pointer file for that tool, helps you seed global/, registers your first project, and reports what it wrote against what it skipped. Running it again is safe.
Make a private repository from the scaffold
Copy or fork it into a repository of your own, keep it private, and clone it. Everything after this happens inside that folder.
Open it in the tool you already work in
Claude Code or Codex — that is where the onboarding agent runs. Obsidian is one way to look at the folder afterwards and is not needed to start.
Ask for it
In Claude Code the scaffold ships the agent that does this, so any of these is enough:
- set this up
- activate the hub
- onboard me
In any other tool, paste this as your first message instead:
activation · paste into any other toolscroll →
Read ADAPTER-PROMPT.md at the root of this folder and follow it.
what the setup agent cannot do
It runs with file tools only — no shell, no network. It cannot run git init, add a remote, or push, because it has nothing to run them with. That is a fact about what it is able to do, not a promise it makes. Anything touching Git is yours to run.
10 next
Where to go from here
This page is the argument. The owner's guide is the reference — the setup walkthrough, every command with its real flags and gates, the tree, the budgets, the two plans, and an honest list of what is not built yet.