CortexBuild Upgrade Guide

Public copy of this guide (no login): https://dist.cortexbuild.dev/guides/upgrade.html — always the latest published version. Release notes: https://dist.cortexbuild.dev/guides/releases.html

One guide, both audiences. Part 1–2 and 5–6 are shared; Part 3 is for the human developer, Part 4 is for the AI agent operating the repo (paste it, or let the agent find it here after upgrade). Every step is per-repo, reversible, and nothing below may stall an autonomous session.

Current version: 0.2.59. (cortexbuild version --check tells you if this build is behind.) You don't need to hunt for what changed — after any upgrade the release-note highlights auto-display once in your console, at the first CortexBuild command you run (version, session-start, session-handshake, upgrade, or render). --json invocations get the same news machine-shaped in a whats_new field. Long form: Release Notes · https://dist.cortexbuild.dev/guides/releases.html (public, no login)

Part 1 — The upgrade (5 minutes, reversible)

# 1. Upgrade the package
#    --no-cache-dir matters: pip caches the package index it fetched earlier,
#    and a cached index does not know about a release published after it was
#    fetched — "Requirement already satisfied" while you silently stay on the
#    old version. The index is served revalidate-always, but pip's own local
#    cache from before that can still bite once.
pip install --upgrade --no-cache-dir cortexbuild-core --find-links https://dist.cortexbuild.dev/index.html

# 2. Confirm it took — this also shows the what's-new highlights
#    (needs a valid licence, like every command except `auth`; if it reports
#     `license required`, run `cortexbuild auth refresh` first)
cortexbuild version                  # must print the new version; verify, don't assume

# 3. Preview what a re-render will change in THIS repo (touches nothing)
cortexbuild upgrade

# 4. Apply: snapshot -> render -> validate
cortexbuild upgrade --apply

# 5. Gate: every rendered surface in sync
cortexbuild render --check           # must exit 0

Safety properties you can rely on:

upgrade --apply takes a byte-identical snapshot first; cortexbuild upgrade --rollback restores it exactly. There is no partially-upgraded state.
If --apply warns that CortexBuild-owned files were hand-edited (CLAUDE.md, .claude/agents/*, .github/agents/*, .cursor/rules/*): those edits will not survive a render. Move the change into the rule/persona source or your org standards pack, then re-apply.
render --check reports drift after any version bump (the framework version is stamped into every rendered file) — that is what upgrade --apply resolves; it is not an error.

Part 2 — What changed that needs attention

Per-release detail lives in the Release Notes, which the CLI also shows you once, in your console, at the first command after an upgrade. The four items below changed behaviour without a config edit and are worth reading once per estate whatever version you came from.

Read these four items once per estate; each changes behaviour without a config edit:

allocation.objective is now live. If .cortexbuild/llm-config.yaml already contains an allocation: block, it was inert before 0.2.18 and now steers model-tier routing (spend). Preview before your next LLM-driven run:

bash cortexbuild orchestrate tiers --title "a typical task for this repo"

No LLM call, no cost — it prints the tier each agent would get and why. objective: [quality, …] raises spend; [cost|speed, …] lowers it; risky tasks (auth/PII, schema, public API, deploy target, multi-system, medium+ risk) are floored off the cheapest tier regardless. 2. Two new foundational rules render into every agent surface: rule-feature-observability and rule-feedback-capture. Your AI tools will begin following them after upgrade --apply — including asking for the task-completion rating described below. 3. Org standards packs can now set profile fields. After cortexbuild standards sync, read the printed apply report: org-mandated compliance regimes land even where the team didn't tick them (never removing local regimes); every other field defers to a local human answer. Wrong value applied? cortexbuild context set <field> <value> — human always outranks org. Rules listed as "Scoped out" were targeted at other repos (applies_to_repos); that is targeting, not an error. 4. The feedback channel exists and is watched. Bugs, improvement ideas, and experience ratings land on the org dashboard (Part 5).

Part 3 — For the developer

Your two minutes of judgement per upgrade, after Part 1:

Read the highlights that printed at cortexbuild version. Anything prefixed WARNING: is a behaviour change of the Part-2 kind — the banner exists precisely so these never surprise you mid-sprint.
Spot-check the render diff if this repo carries local customisations: git diff after upgrade --apply shows exactly what the re-render changed; everything it touched is CortexBuild-owned by definition.
If CI parses render --check output: exit codes never changed, the what's-new banner always prints before the verdict (the last line remains machine-parseable), and render --no-notes suppresses it entirely for exact-output consumers.
If a rollout script greps ANY command's output (a script that scanned upgrade output for "hand-edited" could match the banner's own sentence about hand-edit detection): set CORTEXBUILD_NO_NOTES=1 per invocation, not globally — it suppresses the banner on every command and defers the news (the once-per-upgrade marker does not advance, on any surface, --json included) so a later interactive session still shows it. A globally-exported value means you never see release notes at all.
Committing governance surfaces from automation: never hand-roll the path list (documented failure modes include committing a licence file by mistake, and a Windows argument-length limit on a very large path list). The safe-to-commit set is a command, and the pathspec pipe never touches the OS argument limit:

bash cortexbuild git paths --commit-set --null > .cb-paths && git add --pathspec-from-file=.cb-paths --pathspec-file-nul && rm .cb-paths

Its output structurally excludes license/, usage/, telemetry/, memory and backups — so it is safe even with git add -f in dotfile-ignoring repos. - Multi-repo automation from a hub directory: cortexbuild init run <path> licenses against the target path (0.2.21) — no more cd into each repo; cortexbuild version -r <path> scopes the what's-new bookkeeping the same way. - Troubleshooting — see Part 6.

Part 4 — For the AI agent

You operate this repo; these are standing behaviours from the rendered rules, restated here for the upgrade moment.

a. File feedback — yours and the user's (rule-feedback-capture):

When YOU hit friction — something broken, or a concretely better way:

bash cortexbuild feedback submit --kind bug --source ai-tool -m "<what is wrong>" --feature <key> cortexbuild feedback submit --kind improvement --source ai-tool -m "<what would be better>"

At the completion of each user task in an interactive session, ask one line — "How was this task? 1–5, anything to pass on?" — and record it:

bash cortexbuild feedback submit --kind experience --source user --rating <1-5> -m "<comment>" --task-id <id>

Rules: never prompt in a non-interactive/CI session; a skipped answer is a valid answer — never nag; never put secrets in feedback (the client refuses them — rewrite the message, don't fight the refusal); "recorded locally (no collector)" is a ⚠ to surface, not a success synonym.
Org-side (0.2.22): if your org enables GitHub issue sync, every bug you file becomes a tracked issue automatically and its resolution status appears on the org Feedback dashboard when the issue closes - your reports are answered visibly, not into a void.
Delivery is now persisted per record (0.2.21): cortexbuild feedback list shows delivered / local-only for every record, and cortexbuild feedback flush re-pushes anything that never reached the collector — a submission whose output you did not capture is no longer unverifiable afterwards.

b. Preview model spend before LLM-driven runs:

cortexbuild orchestrate tiers --title "<task>" [--auth|--schema-change|--public-api|--deploy-target]

As Planner: decompose tasks into subtasks and suggest the cheapest tier each subtask's risk allows in your ## Subtasks & Model Plan table. Risky subtasks never get fast_cheap. Governance clamps what you suggest and records both your ask and any correction — suggest honestly, don't pre-clamp.

c. If allocation.objective already exists in this repo's config, it just went live (Part 2.1): run orchestrate tiers once and show the operator the effect before your next LLM-driven run.

d. After standards sync, read the apply report and surface any compliance-overridden lines to the operator — an org mandate landing is correct behaviour, but never silent behaviour.

e. Never: hand-edit rendered files (next render overwrites them — change sources or org packs instead); stall waiting for a rating non-interactively; report "sent" when output said "recorded locally"; skip the experience ask because it feels awkward — one line, and skipping it loses the org its earliest quality signal.

Part 5 — Verify, then report (both audiences)

"Done" means read back, not assumed (rule-verify-the-claimed-state):

cortexbuild version                      # the new version — verify, don't assume
cortexbuild render --check               # exit 0
cortexbuild feedback submit --kind improvement --source ai-tool \
  -m "upgrade smoke check" && cortexbuild feedback list             # channel works
cortexbuild feedback flush               # re-push anything still local-only
cortexbuild telemetry record --features upgrade,render --tools bash --json
# read `pushed` in the output: `pushed: false, push_attempted: false` means no
# collector is configured in this repo — surface it, don't bury it.

Then close the loop: update the tracker/work item with the version, the render-check result, and any ⚠ surfaced (rule-connected-service-usage).

The question this answers: "we have eight developers on one repository — does everyone run the upgrade, or just one of us?"

Both, but they are different actions. CortexBuild has three things with three different lifecycles, and conflating them is what makes team upgrades go wrong.

What	Where it lives	Who handles it
Your licence	`.cortexbuild/license/` — gitignored, it is a credential	Every developer, once per checkout they work in
The CLI package	pip, on your machine	Every developer
The rendered governance	`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/`, `.github/copilot-instructions.md`, `.cortexbuild/` — committed	One person, once per upgrade

The rendered files are generated and shared. If five people each run upgrade --apply, you get five conflicting diffs of byte-identical generated content and a merge nobody enjoys. The package, by contrast, is per-machine — nobody can upgrade it for you.

The sequence

One person — call them the upgrade driver:

pip install --upgrade cortexbuild-core
cortexbuild upgrade                 # preview; touches nothing
cortexbuild upgrade --apply         # snapshot -> render -> re-check drift
cortexbuild render --check          # prove every surface is in sync

# Stage exactly the governed set — never license/ or usage/, and immune to the
# Windows argument-length limit:
cortexbuild git paths --commit-set --null \
  | git add --pathspec-from-file=- --pathspec-file-nul
git commit -m "chore(cortexbuild): upgrade to <version>"

Everybody else, after that lands:

pip install --upgrade cortexbuild-core   # to the SAME version
git pull

That is all. No second re-render — the surfaces are already correct in the commit they just pulled.

The failure this ordering prevents

A developer still on the older CLI who runs cortexbuild upgrade --apply will render the repo backwards to their version and commit a downgrade.

As of 0.2.22 this is blocked by default. upgrade --apply compares the version the repo is rendered at against the version you have installed (semantic ordering — 0.2.9 -> 0.2.10 is an upgrade) and refuses to render backwards, naming the remedy:

pip install --upgrade cortexbuild-core

The preview marks the direction long before --apply: a stale CLI sees framework: 0.2.22 -> 0.2.19 DOWNGRADE on cortexbuild upgrade, and --json carries is_downgrade: true.

A deliberate rollback or version pin remains possible with --allow-downgrade: the command says DELIBERATE DOWNGRADE loudly and records deliberate_downgrade in the snapshot metadata, so a later reader can tell an intentional rollback from an accident.

Still: upgrade your package before you touch the repo, and let one person drive the re-render — the guard makes the mistake loud, not impossible.

The gate that makes this safe

cortexbuild render --check

Run it in CI as a blocking check. It catches both directions of the problem:

somebody upgraded and forgot to commit the re-render, and
somebody rendered the repo backwards with a stale CLI.

Without it, both mistakes are silent until an agent starts behaving to the wrong rules — which is a confusing thing to debug from the symptom end.

After upgrading, confirm your data actually arrives

Installing the package is not the same as reporting. telemetry record prints OK even when nothing left the machine — the local ledger write always succeeds — so every developer should finish an upgrade with:

cortexbuild telemetry doctor

If it reports no collector (LOCAL-ONLY), the repository has never declared one — a repo adopted before the collector step was in the onboarding guide is in this state, and every event it ever recorded is still only on disk. Declare it once and commit the file (it holds no secrets), then run doctor again:

cortexbuild telemetry configure --org-id <your-org-id> --project-id <estate-or-team-name>
git add .cortexbuild/telemetry.yaml
git commit -m "chore: declare the CortexBuild collector"

It checks the six things that silently stop delivery and ends with a real push, reporting whether the collector accepted it:

Check	What its failure looks like on the dashboard
Collector configured	Nothing from this repo, ever
Collector config committed	Works for whoever configured it, silent for everyone else and for CI
Licence verified	Nothing arrives -- the most common cause
Client version	Clients older than 0.2.31 can no longer send usage data; upgrade
Identity attributed	Data arrives, but as a device id instead of a person
AI host detected	"AI tools in use" reads empty

--json for a fleet sweep; it exits non-zero only when something would truly stop delivery, so it can gate an onboarding script.

If it prints license required, that IS the diagnosis: run cortexbuild auth activate --key <your-token> and re-run it.

Keeping a team on one version

Pin cortexbuild-core in whatever your project already uses (requirements.txt, pyproject.toml, constraints.txt), and raise the pin in the same pull request as the re-render. Then "who is on which version" stops being a question you ask people and becomes a fact in the lockfile.

To check any repo at any time:

cortexbuild version -r /path/to/repo   # what that repo is rendered at
cortexbuild version                    # what you have installed

When those two disagree and the repo is ahead, upgrade your package — do not re-render.

Licences belong to a person, not a repo

A licence belongs to a person. You activate it once in each repository checkout you work in, and each machine you use takes one device seat.

cortexbuild auth activate --key <their-token> --url https://license.cortexbuild.dev

The token is written under .cortexbuild/license/ in that checkout, which is gitignored deliberately: it is a credential, and one person's activation does not license a colleague. A seat is consumed per device, up to the licence's device cap — so the same person on a laptop and a desktop uses two of their own device slots, not two seats.

Upgrading the package does not re-activate anything. Existing activations keep working across upgrades.

Quick reference

Situation	Action
New release is out	Driver upgrades + re-renders + commits; everyone else upgrades package + pulls
You joined the repo	`pip install cortexbuild-core`, then `cortexbuild auth activate` with your own key
`render --check` fails on your branch	You are on an older CLI, or the re-render was not committed. Upgrade, then re-check before re-rendering
You are unsure who should upgrade	Package: you. Repo files: one person

Part 6 — Troubleshooting

Symptom	Fix
`render --check` exits 1 right after upgrading	Expected version-stamp drift: run `cortexbuild upgrade --apply` (or `cortexbuild render`), then re-check
Want the old state back	`cortexbuild upgrade --rollback` — byte-identical restore of the pre-upgrade snapshot
`--apply` refuses: hand-edited owned files	Your edits live in renderer-owned files; move them to the rule/persona source or org pack, then `--apply --confirm`
`license required` on a command	`cortexbuild auth status`; a licence belongs to a person and is activated once per checkout — see your org admin
Feedback refused	The refusal names its constraint (secret-shaped text, injection-shaped text, size cap, missing rating). Fix the message; never work around the guard
CI output assertions broke on `render --check`	The banner prints before the verdict — the last line is unchanged; use `render --no-notes` for exact-output snapshots
The what's-new banner never appeared	It shows once per version change per checkout; `--json` runs carry it as `whats_new` instead. First-ever run is a silent baseline by design

Friction with this guide itself? cortexbuild feedback submit --kind improvement -m "..." — that channel is watched, and it reaches the people who fix things.

Published 2026-10-22 12:34Z. Latest release: 0.2.59. This page is generated from CortexBuild's own documentation and is kept in sync automatically.