Release notes
What each release changed
Newest first. The latest published release is 0.2.59. Upgrade with pip install --upgrade cortexbuild-core --find-links https://dist.cortexbuild.dev/index.html then cortexbuild upgrade --apply.
0.2.59 latest
- New: adoption figures in the admin portal are now exact on Postgres-backed collectors, instead of being computed from only the newest 5,000 events. On busy organisations the numbers may be higher than before.
- New: the AI Adoption page has a Weekly tab that compares each week with the one before, with a week selector and a client report download. The download carries category counts only: it never includes guard or rule names or any person identifier, and repository names are included only if you opt in.
- New: operators can now produce an organisation adoption report from a documented script, the AI Adoption view shows a tile for usage-metering timeouts, and the Maintenance Jobs view (platform operators) shows how many synthetic probe reports the tracker sync skipped.
- New: the rules now require that when a change applies a stated principle, every place the principle applies is listed and checked for the intended behaviour, not just the first one.
- Changed: adoption pages may lag new activity by up to 45 seconds because results are now cached briefly.
- Changed: the feedback list
limit now caps the number of reports returned (newest first, up to 50,000) rather than the number of events scanned, and the response says whether the list is complete. - Changed: usage recording at the end of a turn is given more time to finish (6 seconds instead of 2) before it gives up.
- Changed: the list of files CortexBuild commits for governance no longer includes files that were never tracked; lists of blocked payloads are now size-limited; the local session notes folder is now ignored by git.
- Changed: telemetry events the server rejects (for example a licence that belongs to a different organisation than the repository's configuration) are no longer retried on every turn; they are kept in a local rejected list that
cortexbuild telemetry show reports, so the configuration can be fixed. - Fixed: read-only project viewers can no longer read organisation-wide data: telemetry events, feedback reports, adoption pages (including the weekly report and its download), rollups and the feedback-to-issue mapping. Their Overview shows "Adoption figures are unavailable".
- Fixed: release-verification probes marked by a superadmin are never filed as issues; ingest strips the marker from ordinary submissions and applying it is recorded in the audit log.
- Fixed: the snapshot taken before an upgrade or a standards change no longer depends on renaming a directory (which file watchers could interrupt). It now commits with a marker file, refuses symbolic links and junctions in the backup location and inside the folders it captures, refuses
.git paths and alias ids, and a reused backup id is written so that an older client restores nothing rather than deleting files. - Fixed: three lint errors were cleared.
- Fixed: the end-of-turn hook no longer waits on the telemetry server: it spends at most about three seconds on the network per turn, measured on the clock even when the server answers one byte at a time, sends the new event before retrying older ones, and backs off while the server is unreachable or answers too slowly.
- Fixed: text from the telemetry server, such as the reason it gives for refusing an event, is cleaned of terminal control sequences and can no longer crash
cortexbuild telemetry record or cortexbuild telemetry show; a corrupt or implausible push backoff file is ignored instead of silencing telemetry; and an answer such as 404 from a stopped server keeps the event for a later retry instead of discarding it. - Changed:
cortexbuild telemetry flush, including --ledger, is now bounded per call and overall: it stops after 120 seconds or at the first failed send (and the spool flush also after three refusals in a row), and says which. - Fixed: the collector returns 503 within seconds when its database pool is unavailable instead of hanging, and its deep health check restarts an unhealthy replica. Concurrent deep health checks share one database check, reused for 5 seconds.
- Action required: self-hosted collectors need no database migration; redeploy the collector image as usual.
- Action required: Self-hosted collectors: deploy this image before pointing any liveness probe at
/health/deep; an older image answers 404 there and the probe restarts the replica in a loop. - Action required: if your organisation uses the project viewer role, it can no longer read organisation-wide data (telemetry events, feedback reports, adoption including the weekly report and its download, rollups, and the feedback-to-issue mapping). Give those users the org admin role if they need organisation-wide figures.
- Action required: if you call the feedback list API with
limit, it now caps the number of reports returned, not the number of events scanned. - Action required:
cortexbuild upgrade and standards changes now refuse to take a snapshot when a backed-up folder contains, or is, a symbolic link or junction (for example a linked AGENTS.md, CLAUDE.md, .claude/agents or .cortexbuild/rules). Replace such links with real files or folders before upgrading. Backup ids ending in a dot or a space, or that are Windows device names, are refused. - Action required: adoption breakdowns on large organisations are now exact, so figures may be higher than in 0.2.58, and pages may lag new activity by up to 45 seconds.
0.2.58
- New: org admins can attach screenshots and log files to feedback in the admin portal -- up to 5 files per report (PNG, JPEG or WebP images up to 10 MB each; .txt, .log, .json or .csv files up to 5 MB each; 25 MB per report). Location and other hidden metadata are removed from images automatically, and a text file that appears to contain a password or key is refused. Attachments are kept for 180 days.
- Changed: the documentation site has been reorganised around installing, using and administering CortexBuild, and the release notes now list what is new, changed, fixed or needs action in each version.
- Fixed: a response recorded without a session identifier is no longer counted twice in response totals.
- Action required: self-hosted collectors must run
cortexbuild server migrate before rolling out this version.
0.2.57
- Changed: this release also includes everything from 0.2.56, which was not published on its own.
- New: on Claude Code, token usage is now measured automatically for each response, so you no longer need to record it by hand.
- Action required: self-hosted collectors must run
cortexbuild server migrate before rolling out this version.
0.2.56
- New: usage dashboards now lead with a single, consistent token figure per person, labelled as measured or estimated.
- New: organisation admins can submit feedback directly from the admin portal.
- Security hardening in feedback reporting; upgrading is recommended.
- Fixed: licence detection is more reliable across different folder layouts, and licence commands now report which install they acted on.
- Fixed: a licence-refusal message now explains the actual reason instead of a generic one.
- Fixed: usage recording in long sessions is now reliable for the whole session, not just its first part.
- Fixed: telemetry no longer drops events that contain a Windows-style file path.
- Fixed: the Executable Hooks guide is now linked from the documentation navigation.
0.2.55
- New: executable hooks let supported AI tools run governance automatically -- a build-status check at the start of a session, usage recording at the end of a turn, and a guard against editing legacy code during a modernization effort.
- New: CortexBuild is available as a Claude Code plugin.
- New: when a repository is being modernized with a supported plugin, its progress is visible in the admin portal.
- New: if a governed task's review does not complete, the next session now reports where it stopped and suggests how to resume.
- New: the collector now continuously monitors the health of CortexBuild's own services.
0.2.54
- New: an AI Adoption screen in the admin portal shows active developers, governed activity, recorded usage, and which agents, rules, tools, features and AI hosts your teams use.
- New: you can open any usage event to see exactly which rules, agents and guards applied to it.
- New: organisation admins can see their own repositories' reporting health and get notified when it goes quiet.
- New:
cortexbuild reference add/list/check lets you register generated reference material (such as a schema or API inventory) so agents can find it reliably. - New: repositories being modernized with a supported plugin now get extra governance automatically -- legacy code stays protected, and each stage is tracked.
0.2.53
- New:
cortexbuild standards pack <dir> --publish publishes a whole rules directory to your organisation in one step, validating everything first. - New: a standards pack can now include custom agent personas, not just rules.
- New:
adopt --ssot <dir> supports teams that already have their own rules setup, without re-importing what they already govern. - Changed: a repository whose usage recording is off now shows as 'not being counted' rather than looking like zero adoption.
- New: the Feedback screen shows the resolution status of each report you filed, with the version it was fixed in.
0.2.52
- New:
cortexbuild integrity scans a repository for signs of supply-chain tampering (hidden or obfuscated code) and reports findings with file and line. Security hardening; upgrading is recommended. - New: governance branches can now be verified to touch only approved paths (
git paths --verify), and upgrade --apply refuses a tree with unapproved changes -- pass --allow-dirty "<reason>" to proceed anyway and record why. - New:
cortexbuild doctor can check whether your repository's branch-protection settings meet recommended standards, when connected to GitHub or Azure DevOps. - Fixed: a repository-local configuration override for enabled AI-tool targets is now read correctly; if you enabled an extra target this way before, re-check that it took effect.
- New:
init now sets up telemetry configuration automatically from your licence, matching adopt and onboard. - New:
telemetry flush --ledger can push events that were recorded locally before a collector was configured.
0.2.51
- Fixed:
auth status --json no longer labels the short-lived device lease as your licence's expiry, which could be misread as your licence ending soon. The lease and the licence term are now reported separately and clearly labelled.
0.2.50
- New:
cortexbuild version --check tells you when your install is behind the latest release and how to upgrade. - New: free, no-login guides for getting started and upgrading are published online, along with a release-notes page.
- New:
adopt and onboard now configure telemetry reporting automatically once your licence verifies. - Fixed: an error message from the licence gate could end up written into a file instead of being shown to you; it is now shown correctly.
- Fixed:
eject could restore an outdated backup in some repeated setup/removal cycles; it now checks before restoring. - Fixed: several detection and console-output bugs, including a crash on some Windows terminal configurations.
- Changed: usage reporting is clearer about which repositories are not yet being counted.
- Action required: self-hosted collectors must run
cortexbuild server migrate before rolling out this version.
0.2.49
- New: rendering now supports Gemini-based AI tools; enable with
gemini: under render targets. - New:
render now tells you when it detects an AI tool it is not writing rules for, so you can enable it. - New: an organisation can require that usage events include a token count.
- Fixed: telemetry reporting from a linked git worktree now authenticates correctly.
- Fixed: a couple of warning messages were unreadable on some Windows consoles.
- Fixed: the package's listed homepage now points at the public site instead of an internal location.
0.2.48
- New:
cortexbuild rules new and cortexbuild agents new let you register your own repository-local rules and agent personas safely. - Fixed: the advisory for repository-local rules now counts only the files that actually take effect.
- Fixed:
skills new now checks against everything actually loaded, so a skill referencing a rule you just added is no longer incorrectly refused. - New: rendered files now clearly state where their editable source is.
- New: a new guide, 'Adopt your own governance', walks through bringing an existing rules setup into CortexBuild.
0.2.47
- New:
telemetry record now warns when no token count was supplied. - New: a hand-authored recurrence ledger in an unexpected format no longer blocks every ledger command;
cortexbuild ledger migrate can convert it, and init/upgrade now create the file in the right shape from the start.
0.2.46
- Action required: 0.2.45 was published briefly and withdrawn the next day. If you installed it, upgrade to this release, which includes everything 0.2.45 had plus further fixes, under a new version number.
- Fixed: the conformance trend chart had never recorded a data point; it now records correctly. Self-hosted collectors must run
cortexbuild server migrate. - Fixed: a repository that had not been re-rendered recently could be missing local protection for its runtime folders;
render now always ensures it is in place. - Fixed: regenerating an analysis report from an out-of-date checkout could silently shrink it; this is now refused unless you explicitly force it.
- Fixed: repository-local rules that duplicated a built-in rule ID (and so had no effect) are now reported clearly instead of silently doing nothing.
0.2.45
- Fixed: licence lease renewal could time out under some conditions, causing a licence to appear expired when it was not; the renewal time budget has been increased.
- Fixed:
auth status could show a technical lease timestamp in a way that looked like your licence's expiry date. The lease and the licence term are now shown separately (see also 0.2.51). - New: a licence that is missing or has ended now warns you in advance, inside your AI tool's response, before it stops working.
- Fixed: a licence stored per checkout was not inherited correctly by a linked git worktree, leaving it unlicensed; this is fixed for a checkout's own worktrees.
- Fixed: a rename operation could leave old, removed files still tracked by git; removals are now tracked correctly.
- New: committed analysis reports now record when they were generated and from which commit, and
doctor warns when one is far behind. - New:
cortexbuild skills new lets you register a hand-written skill into the governed setup instead of writing it directly into a rendered folder. - Fixed: an unrecognised industry value now clearly states that it does not activate any preset, instead of silently doing nothing.
- Fixed: a few status messages (
doctor, fleet push, telemetry flush) now describe what they actually checked or did, rather than overstating it.
0.2.44
- Fixed: a command that failed partway through could show a raw internal error instead of a clear message; failures now show a clean message and save a crash report you can share when asking for help.
- Fixed: an underlying file-locking issue that could cause the failure above is also resolved, with an automatic retry.
- Fixed: some suggested install commands were missing part of the command when printed to the console; this is corrected.
- Fixed: usage-tracking coverage was undercounting in some cases because certain internal events were included in the total; this is corrected, and the excluded events are now shown separately.
- Fixed: the usage dashboard could count one person as multiple people across different machines; it now counts people correctly, and this also corrects historical data.
- Fixed: a governance check that ran but did not record that it ran could leave your conformance score looking stuck even after a fix; it now records correctly.
- Fixed: a codebase with no supported language parsers installed could show its dependency graph as up to date when it was actually empty; this is now detected.
- Fixed: deleting a repository-local skill did not remove its rendered copies; it now does.
- Fixed: an editable (developer) install could report a stale version number; this now shows correctly.
0.2.43
- Changed:
cortexbuild server migrate now clearly tells you whether your installation needs to run it at all -- self-hosted collectors do; if you report to a collector someone else runs, there is nothing to run.
0.2.42
- Fixed: the message shown when a licence is missing now gives you the one correct activation command, instead of a command that led to a second error.
- Changed: the documentation is clearer that a 'licence required' refusal is not the same as telemetry's fail-open behaviour -- nothing is recorded when a command is blocked from running at all.
- Fixed: the reminder to commit newly rendered governance files now also appears after
render and upgrade --apply, not only a few other commands. - Fixed:
cortexbuild server migrate no longer crashes on a brand-new, never-migrated database.
0.2.41
- New: the upgrade procedure now ships as a skill rendered directly into your repository, so your AI tool can read it without leaving your project.
- Fixed: the admin portal's licence list could fail to load, caused by a missing permission on a newly added column. Self-hosted collectors: 0.2.40 alone is broken; run
cortexbuild server migrate. - Fixed: commands referenced by rendered skills are now checked to make sure they actually exist, the same way rule-referenced commands already were.
0.2.40
- New: a licence seat can carry the holder's display name, which now works consistently regardless of which collector backend an organisation runs.
- Self-hosted collectors ONLY: run
cortexbuild server migrate before rolling out this version. If you report to a collector someone else runs, that is their database and there is nothing for you to run.
0.2.39
- Fixed: repository-local rules written from feedback now render correctly on their own, without requiring an organisation standards pack.
- New: a new advisory tells you when a governed file has changed but is not yet committed, so a fix does not get lost when the branch is discarded.
- Fixed: the message about a repository-local rule being overridden now names exactly which files are affected, instead of implying the whole directory is inactive.
0.2.38
- New:
cortexbuild telemetry doctor checks the most common reasons usage data is not reaching your dashboard and does a real test push, reporting whether it was accepted. - Fixed: usage recording is now correctly grouped as one row per person rather than one row per machine.
- Fixed: searching the usage dashboard by email now works correctly.
- Changed: the 'time with AI' figure is now shown as a range rather than a single number, since it is inherently an estimate.
0.2.37
- New: the Scorecards screen now shows which licensed features your repositories are entitled to but are not using.
- New: a repository's conformance score now shows which factors it is losing the most points to.
- New: conformance scores are now tracked over time, so you can see whether an estate's score is improving. Self-hosted collectors must run
cortexbuild server migrate. - Changed: the scorecard now also shows the median and the range of scores, not just the average.
- Security hardening in licence-seat handling; upgrading is recommended. Self-hosted collectors must run
cortexbuild server migrate.
0.2.36
- Fixed: usage reporting now correctly recognises one person across multiple machines as a single person, rather than counting each machine separately.
- New: a Standards screen lets an admin author rules and skills in the portal and publish them to every licensed repository in the organisation.
- New: a Scorecards screen shows every repository's conformance score in one place, with organisation-wide targets and progress tracking.
- New: an Impact screen estimates the value of governance activity (guards fired, issues prevented) against a cost figure you supply; nothing is shown until you provide the input it needs.
0.2.35
- Fixed: the usage dashboard's person filter now accepts an email address, not only the internal identifier.
- New: a 'Usage by person' table shows activity, tokens, AI tools, agents, rules and features used per person.
- Fixed: the 'AI tools in use' view now correctly shows the AI hosts your teams run, rather than lower-level tool names.
- New:
cortexbuild conformance --share score.html generates a self-contained, offline governance-score page you can share.
0.2.34
- Security hardening in telemetry authentication for onboarded repositories; upgrading is recommended.
0.2.33
- Action required: self-hosted collectors must run
cortexbuild server migrate before rolling out this version, to support authenticated usage reporting.
0.2.32
- Fixed:
auth activate with a service-issued token and no explicit service URL now activates correctly instead of showing an unrelated error.
0.2.31
- New: the telemetry collector can now authenticate reported usage against your licence, so dashboards show the registered person instead of an anonymous identifier.
- Security hardening in usage-event authentication; upgrading is recommended. Clients older than 0.2.31 can no longer send usage data; upgrade.
0.2.30
- Fixed: tasks submitted through the web control plane now go through the same governed task store as the command line, so they are tracked and auditable the same way.
0.2.29
- Fixed: a packaging issue that could cause a crash on a fresh install of the previous release is resolved.
0.2.28
- New:
cortexbuild task import/approve/dispatch and orchestrate run --from-task give you one governed task record from import through execution. - Fixed: re-authoring a task with the same content no longer resets its approval status.
- Fixed: usage events no longer carry your email address directly; a signed identifier is used and resolved to your registered address only inside CortexBuild's own service.
0.2.27
- Fixed:
eject could restore the wrong backup in some cases; it now restores only the correct pre-adoption backup and preserves your later edits. - Fixed: the local task commands (
task author/list/distribute/bind-check) are now reachable; they existed but were not wired up. - Fixed: removing an outdated rendered-file marker no longer discards content you wrote below it.
- Fixed: a check for stale file references now correctly reflects what a fresh clone of your repository would see.
0.2.26
- Fixed: an error message from
render --check suggested a command that does not exist; it now names the correct one, and every command mentioned in this codebase's own messages is now checked to make sure it exists.
0.2.25
- Changed: the files CortexBuild renders into your AI tools are now much smaller, while keeping every enforceable rule; other rules are summarized with a pointer to the full text.
- Fixed:
render no longer reports success while silently skipping a file it could not safely update; it now fails clearly and tells you how to recover. - Fixed:
render --check now also catches the case where a file your AI tool depends on exists locally but was never committed.
0.2.24
- Fixed:
eject could delete a file it was supposed to restore in certain sequences; this is fixed, and affected repositories may have a backup available. - Fixed: all-time usage totals were being computed from a rolling window and could appear to decrease as usage grew; totals are now computed correctly.
- Fixed: a per-repository identifier could cause one person to be counted multiple times across their repositories; this is corrected.
- Fixed: some git identities (from certain editors or CI runners) were being recorded as anonymous; this is corrected.
- Fixed:
render --check and standards check now fail when a rendered file is ignored by git, instead of only warning. - Fixed: the architecture report agents are told to read is now committable so a fresh clone has it.
- Fixed: a generated report file no longer changes based on your local folder name.
- New:
cortexbuild aggregate (cross-repository ROI rollup) is now reachable.
0.2.23
- Changed: every command now requires a valid licence except
auth, which is how a machine becomes licensed in the first place. - Fixed: a licence lease that lapsed (for example, a laptop left off over a weekend) now renews automatically on the next command instead of the repository silently dropping off reporting.
- New: every user, including on the free plan, now receives a real issued licence, so usage is attributable from day one.
- New: your AI tool is now recorded with its actual name (Claude Code, Codex, Copilot, Cursor and others); set
CORTEXBUILD_AI_TOOL if yours shows as unknown. - Changed: several licensed features now have their usage properly enforced and counted; a few free capabilities (a single-repository workspace, local memory, self-hosted local models) remain free.
- Security hardening in model-provider configuration; upgrading is recommended, and we suggest reviewing your
.cortexbuild/llm-config.yaml after upgrading. - Fixed: feedback totals could drop to zero over time due to a rolling-window calculation; this is corrected (already-affected local counts cannot be recovered).
- Fixed: a failed usage report now explains why (for example, an authentication problem) instead of a generic message.
0.2.22
- Fixed: repository scanning now skips ignored folders more efficiently and handles unreadable files without crashing; a
.cortexbuildignore file is now supported. - New:
upgrade --apply refuses to install an older version over a newer one by accident; use --allow-downgrade if that is intentional. - New: bug reports can automatically become tracked GitHub issues (where an organisation enables it), with resolution status appearing back on the Feedback dashboard.
0.2.21
- Fixed: a batch of reported issues from users is fixed in this release; keep filing reports with
cortexbuild feedback submit. - Fixed: a newly published release is now visible to
pip install --upgrade immediately, without needing --no-cache-dir. - New: set
CORTEXBUILD_NO_NOTES=1 to suppress this banner on every command; suppressed news is shown later, never lost. - New:
cortexbuild git paths --commit-set gives you the exact, safe set of files to commit. - New:
feedback list shows whether each report reached the server, and feedback flush retries any that did not. - New: the admin dashboard gained a Feedback screen, a system-health screen, and daily/weekly active-usage summaries.
0.2.20
- Fixed: a batch of reported issues is fixed in this release.
- Fixed:
upgrade --apply no longer incorrectly flags every rendered file as hand-edited on a version bump. - New:
cortexbuild version --json now exists and includes what's-new information.
0.2.19
- New: release notes now find you automatically. On a version change, highlights are shown once at your next
version, session-start, upgrade, or render command. - New:
--json output carries the same information in machine-readable form. - New:
render --no-notes suppresses the banner for automation that needs exact output.
0.2.18
- New:
cortexbuild feedback submit lets you report a problem, suggest an improvement, or rate a task, from the command line or your AI tool. - New: feature usage and feedback now appear on the organisation dashboard.
- New:
cortexbuild orchestrate tiers previews which model tier each task would use, at no cost. - Action required: if you had set
allocation.objective in your model configuration, it previously had no effect and is now active; review it before your next run.
0.2.17
- Action required: rendered agent files now request a specific model tier for supported AI tools; spend increases on re-render. Set
recommended_model in your rule pack, or pin a model: in the agent persona source, to opt out. - Changed: licence verification no longer requires an optional extra to be installed.
- Changed:
auth entitlements now reports unlicensed and exits non-zero when a licence does not verify, instead of printing a free plan. - Changed: licences now resolve from the repository a command operates on (
--repo-root, or --base for rollout), so a multi-repo script reports a genuine per-repo result. - New: separate download tokens are now available for automated installs, distinct from device activation.
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.