Concepts
Organisations and projects
An organisation holds the context every project shares, such as the brand and the design system; each project reads it as its own and adds what is specific to it. A project can pin a version or differ per field, always with a reason.
One company, one brain: the brand, the customers and the decisions are the same for every team. What differs per project is the mix it adds on top. Epic Context models that with two levels.
The organisation and its org project
Every organisation has one org project: a project of its own kind that holds what the whole organisation shares. Typical blocks are the brand positioning, the tone of voice, the visual identity and components, shared personas, the glossary, legal documents and organisation-wide decisions. Its book opens at /<organisation>, with the shared chapters first and then each project as a chapter.
When the org project's brand, design and decision blocks are created, the most sensitive ones are locked by default (positioning, visual identity, tone of voice, messaging, component specs, decisions), so a change goes through an owner or admin. An organisation can change that list.
Projects
A project is one product, service, programme or department. In the app's menus it is called a workspace. It has its own book at /<organisation>/<project>/book, its own changes feed and its own settings. Anyone who may edit (a member or above) creates one from the organisation's book (New workspace) or from an AI session with create_project; either way it starts with the thirty-four entities as stubs.
How a project inherits
- Live by default. A project reads every org block as it is now, labelled org, as if it were its own. Stubs, section guides and review documents are not inherited.
- Pinned on request.
pin_org_blockmakes a project read one version of an org block until it chooses to follow again. The drift report says what it is missing. - Different per field, with a reason.
override_blockreplaces only the fields you set, in this project only, and asks why. A reader sees one merged block, with the origin of every value. The org block itself is never edited from a project. - Conflicts are resolved for you. A project block with the same type and name as an org block, but without saying it overrides it, wins in that project, and the drift report asks you to turn it into an override with a reason or to remove it.
get_org_context returns what a project inherits and its drift report: pins that fell behind, overrides made against an older version, project blocks that shadow an org block, and overrides whose org block is gone.
From a project to the organisation
When two or more projects override the same field in the same way, propose_promotions writes a proposal to the org block's owner. It never changes the org block itself. An owner or admin can also move a block that turned out to be organisation-wide with move_block_to_org; it keeps its history.
Choosing where a block goes
| It is true for | Put it in |
|---|---|
| Every team and product (the brand, the design system, company-wide decisions) | The org project |
| One product or programme (its features, its roadmap, its journeys) | The project |
| One product, but a shared block does not quite fit | An override in the project, with the reason |
Next
- Relations: how blocks point at what they rest on.
- Writes, changes and locks: what a lock refuses.
- Setting up a project: the first week in a new project.
Last updated: