# Changelog (https://systemhub.com/docs/changelog)

> Part of systemHUB Docs · Connect: Settings → AI Gateway in systemHUB · Auth: OAuth (scoping is workspace-level today — see Getting started) · MCP tools: 48 · Full corpus: https://systemhub.com/llms-full.txt

What changed in the systemHUB MCP and these docs, newest first. The [tool reference](/docs/tool-reference) is regenerated from the stored schema snapshot on every deploy, and states how old that snapshot is; this page records the deltas so a returning agent (or its human) can see what's new at a glance.

## 2026-09-15

- **ChatGPT does need Developer Mode.** [Getting started](/docs/getting-started) told people to skip it and go straight to Create App. That was wrong: ChatGPT requires Developer Mode for any connector that can write, and on Business/Enterprise/EDU creating the app is admin-only. Steps corrected to match the [ChatGPT help article](https://kb.systemology.com/help-center/connecting-systemhub-to-chatgpt-ai-gateway-/-mcp-0).
- **MCP access isn't admin-only, it's admin by default.** We said only admin seats could reach AI Gateway, so a Contributor or Reader could never connect. It's actually a per-role setting an admin can switch on (verified 27 Aug). Corrected on [Roles & seats](/docs/concepts/roles-and-seats#which-roles-can-connect-an-ai), [Getting started](/docs/getting-started) and the home page, with the open edit-enforcement gap stated alongside it.

## 2026-09-07

- **Identity binding is fixed, and these docs were still saying it wasn't.** Since 31 Jul every page warned that a session resolved to the workspace's most-recently-generated token rather than the connecting person. That fix shipped and was **verified in production on 27 Aug** — so for ten days the docs understated systemHUB's own security posture to every agent that read them. Corrected on [Getting started](/docs/getting-started), [Errors & limits](/docs/concepts/errors-and-limits), [Teach your AI](/docs/teach-your-ai) and `llms.txt`. **One gap is still open and now stated plainly:** permission enforcement on *edits* is incomplete — a Reader-level account was observed editing documents it had no edit rights to, while creates and out-of-scope reads were correctly refused.
- **The tool reference can no longer promise it is live.** The build used to fetch the schema on every deploy, and the page said it therefore could not drift. Closing the identity-binding hole also closed the build's only unattended route to that schema — `/mcp/oauth/authorize` now redirects to a consent screen a human must approve, which is correct. The pull failed **silently** and the reference under-reported the product. Three changes: the build now records that it fell back, **the page carries a banner saying how old its snapshot is**, and the "generated from the live schema, so it cannot drift" claim is gone from `llms.txt` and the home page. A snapshot older than 45 days now fails the build outright.
- **Known consequence, stated for anyone reading the reference today:** tools have shipped that this snapshot predates. Call `tools/list` on your own connection for the authoritative set.

## 2026-08-28

- **[Sharing & links](/docs/concepts/sharing-and-links): share links CAN be monitored after all.** We said status codes prove nothing, and stopped there — which left anyone distributing share links with no way to detect a dead one. Because the 404 renders client-side, valid and invalid codes both return HTTP 200, but the rendered pages are unmistakable: ~3,500 characters starting with the document title versus ~100 reading "Oh no! Something went wrong." Render and assert on the title. No auth needed. (This corrects a conclusion the reporter had reached and then disproved himself.)
- **[Organise the library](/docs/guides/organising-content): tags are case-sensitive.** `Sales` and `sales` are separate objects with different UUIDs, so filters and counts only match the exact casing — in one audited library that split a single tag 11 documents to 2. `add_document_tags` matches by exact title and silently mints a new tag for anything that doesn't, so one capital letter forks your taxonomy. Read existing tag titles and reuse them verbatim.

**Four corrections from an independent cold run** (Systems Equal Freedom, 28 Aug). Three were our errors, and one had been reported fixed when it wasn't:

- **We told agents `"parent": "root"` works on `get_folder_tree`. It does not.** The schema *describes* `"root"` as accepted while typing the same parameter `format: uuid`, so it fails validation before reaching the server. [Organise the library](/docs/guides/organising-content) asserted the opposite — we wrote that confidently on 4 Aug while correcting the *create* tools, and got the read backwards. Corrected, and the [tool reference](/docs/tool-reference) now carries a correction callout under `get_folder_tree` printing the upstream description as written and correcting it underneath.
- **A broken example survived the fix that was supposed to remove it.** The 4 Aug entry below records fixing `{"parent": "root"}` on the folder-create tools — but only [Organise the library](/docs/guides/organising-content) was changed. [Draft an SOP](/docs/guides/drafting-sops) kept the same broken call for three weeks, in the first guide a new agent reads. Fixed.
- **Our workaround for the oversized folder tree didn't work.** [Errors & limits](/docs/concepts/errors-and-limits) said to scope with `parent` — but `"root"` is rejected and you have no folder UUID on a first call, so the advice was unusable exactly when it was needed. It now names the route that does work: **`list_documents_by_owner` with `type: 1`**, which returns folders as a flat paginated list with a `materializedPath` on each.
- **…with the catch that route carries.** `list_documents_by_owner` requires an owner, secondary-owner or role filter and gives no indication in the response that filtering occurred. On an account with distributed ownership it returns a partial tree that reads as complete. Documented.

## 2026-08-27

- **Fixed two broken links in the [tool reference](/docs/tool-reference), found in the edge logs.** They were written relative — `(concepts/document-lifecycle)` — and this page is served at `/docs/tool-reference/`, so they resolved to `/docs/tool-reference/concepts/document-lifecycle` and 404'd. Now absolute, **and the build fails on any relative link**, so it can't recur. Found by reading actual request logs rather than by review: the broken URL was sitting in the 404s.

## 2026-08-20

- **Fixed a malformed JSON example in the [tool reference](/docs/tool-reference).** The `add_document_videos_and_media` example lost a closing quote and comma, so an agent copying it would have hit a parse error. Cause was ours: a build-time substitution matched a URL greedily and consumed the delimiter after it. The rule now replaces a whole balanced object rather than editing inside one, **and the build now parses every JSON example it publishes and fails if any of them is invalid** — regression-tested against the exact broken string.

- **`llms.txt` is now stamped at build time.** Its "Last updated" line had read 2026-07-29 for three weeks while the changelog moved on — the exact freshness signal an agent uses to judge whether to trust the file. It now takes the build date automatically, and four canonical facts were synced into it: publish captures the body reliably (the rest unconfirmed), the ~30KB base64 attachment ceiling, the unscoped folder-tree blowout, and that share links are not machine-fetchable.
- **The three `publish_*` tools now carry a correction callout.** Their schema descriptions still claim a version snapshot captures content, description, notes, tags, videos, templates and attachments, while an independent restore test reverted only the body. The [tool reference](/docs/tool-reference) prints the upstream description **as written** and then corrects it underneath — the generated reference is never silently rewritten, so a future schema fix will make the callout visibly redundant instead of invisibly wrong.
- **Fixed an example in the tool reference that could not work.** The `reviewDate` example was `2025-06-15` — a past date, which the API rejects, since `reviewDate` must be today or later. An agent copying it from our own documentation would have burned a call on a guaranteed validation error.
- **SEO hygiene:** every page now carries a `rel=canonical` on the `www` host and its own meta description (all fifteen previously shared one), and the home page no longer renders its title twice as "systemHUB Docs · systemHUB Docs".
- **Added a note at the top of every page** stating that this is the MCP/AI reference and pointing humans at [help.systemhub.com](https://help.systemhub.com), so someone who lands here from search knows within a line whether they're in the right place.

## 2026-08-19

- **[Authoring content](/docs/concepts/authoring-content): made the attachment advice actionable.** The page already said "use `fileUrl`, not base64", but justified it on **cost** ("pays for the content twice"), which reads as an optimisation you can skip. It isn't: above roughly **30KB the base64 path stops working**, because the encoded string has to pass through the tool call as one literal and agent harnesses truncate a tool output that large. The page now states the ~30KB ceiling as a hard limit rather than a preference.
- **Corrected the Drive example, which would have sent people to the wrong URL.** The old text said "a Drive share link" works as a `fileUrl`. It does not — `drive.google.com/file/d/<ID>/view` serves an **HTML viewer page**, and attaching it succeeds while silently storing that HTML instead of the file. There is now a three-step recipe for attaching a local file (upload → link-readable → `uc?export=download&id=<ID>`), plus the general rule that any host returning raw bytes will do.
- **Added the verification step.** A wrong URL does not error — `add_document_attachments` returns success and the attachment contains the interstitial. Nothing in the response reveals this. The page now says to fetch the returned `downloadUrl` and checksum it against the source before treating the attachment as done.
- **Why this changed:** an agent attaching a 75KB markdown file to a Business Brain page burned three failed approaches (truncated base64, a blocked static-host deploy, a blocked verification fetch) before landing on the Drive `fileUrl` route — with the correct answer sitting in these docs the whole time, too softly worded to act on. Guidance that is technically present but not decisive is guidance an agent will walk past.

## 2026-08-18

- **Three corrections from an independent re-test** (Systems Equal Freedom, 16 Aug), all cases of these docs being more confident than the evidence supports:
  - **Stopped repeating an unverified claim about versions.** [Document lifecycle](/docs/concepts/document-lifecycle) and the home page called each publish an "immutable snapshot", echoing `publish_*`'s own description. An independent UI restore test reverted **only the body content**, leaving notes, tags, review date and comments untouched. The discrepancy is open with the product team; until it's settled the docs describe a version as a reliable record of the **body** and say plainly that publishing is not a safety net before an agent rewrites metadata.
  - **[Sharing & links](/docs/concepts/sharing-and-links): flagged that a `get_` tool can write.** `get_document_share_link` **mints a public no-login URL** when the document has no code yet. The page mentioned this as a convenience ("generates one if missing"); it now warns that calling it while auditing a library, or while operating deliberately read-only, creates the exposure you were checking for — and points at the `shareLink` field on reads as the non-mutating alternative.
  - **[Errors & limits](/docs/concepts/errors-and-limits): corrected the folder-tree figure.** The page said ~69KB on a 231-document library. On a 396-document library it is **~180KB and exceeds a mainstream AI client's tool-output limit outright**, so the call fails rather than returning something large. With no depth, page or limit parameter there is no supported way to walk the tree in pieces — stated now, because the old figure made it sound survivable.

- **NEW guide — [Publish your AI's skills](/docs/guides/publishing-ai-skills).** Teams are writing AI skills (skill files, agent playbooks, custom instruction sets) that never leave the laptop they were written on — the same invisibility problem systemHUB already solves for processes. The guide documents the pattern: an index page grouped by business function and described by *outcome* rather than mechanics, a page per skill with the file **attached** via `add_document_attachments` (a page describing a skill is a brochure; a page carrying the file is installable), and a hard split between business-wired and genuinely shareable skills. Includes the multi-file reality — `.zip` is rejected and only document types attach, so a skill that's a folder of scripts needs flattening or linking.
- **Fixed a parameter error** in [Draft an SOP](/docs/guides/drafting-sops): the versioning example passed `publishTitle` to `publish_system`. That parameter belongs to `create_system`; `publish_*` takes `title`, and the schemas are `additionalProperties: false`, so the example as written would have been rejected.
- **Unknown URLs now return a real 404.** With no `404.html` in the deploy output, Cloudflare Pages had been falling back to the site index and answering **200 for every unmatched path** under `/docs`. Harmless for a human, but this surface is built for agents: an AI that guessed or constructed a URL was told "200 OK, here are the docs" and had no way to learn the page didn't exist. Unmatched paths now 404 honestly, and the 404 page points at `/docs/`, `llms.txt` and the tool reference so a wrong guess still ends somewhere useful.
- **Fixed a self-contradiction on [Getting started](/docs/getting-started).** The "Connecting your team" section still opened with the pre-correction claim that the token is company-level and there is "one token per workspace, not one per person" — then said the opposite two paragraphs later. The stale wording dated from 31 Jul and was superseded that same day by a live test, but was never deleted. Caught by a client asking whether generating their own token would disrupt their admin's. It would not. The section now states plainly that **the server URL and company alias are company-level while the token is per-person**, and separates the two questions that were being conflated: *who holds a token* (per-person, settled) versus *which identity a session resolves to* (a known open issue, cross-linked rather than restated).
- Also removed the "multi-user connection is being confirmed / field reports conflict" warning from the same section. That was answered on 31 Jul and the field-tested joining procedure directly below it has been the documented answer since.
- **Answered the last open question in that section.** It said we were "confirming which roles can self-serve" a token. That's settled: **AI Gateway is on admin seats**, so a non-admin can't reach the screen and can't complete the flow at all. Stated directly now, and cross-linked to [Roles & seats](/docs/concepts/roles-and-seats), because the consequence matters more than the mechanic — a connected agent has admin-level reach.

## 2026-08-08

- **Tool renamed: `generate_document_share_link` → `get_document_share_link`.** The rename happened on the live MCP after our last schema pull, so the docs were pointing agents at a tool that no longer exists. Caught in technical review before the public flip. Snapshot re-pulled from the live endpoint and all references updated. (Earlier changelog entries keep the old name — they're a record of what was true at the time.)
- Reminder for maintainers: **the schema snapshot goes stale.** Re-pull from the live MCP endpoint as part of any deploy that matters, not just when tools are added.

## 2026-08-07 (later)

- **[Tool reference](/docs/tool-reference) now documents response shapes.** Every one of the 48 tools gains a generated **Returns** table with field names, types and one level of nesting — so `state` vs `documentState` and `reviewDate` vs `review_date` are answerable from the page instead of by calling each tool and reverse-engineering the response. Generated from the live schemas like the rest of the page, so it can't drift.
- **Corrected the review-debt recipe** on [Organise the library](/docs/guides/organising-content) and [Audit access](/docs/guides/auditing-access). Both said to find overdue documents by scanning for `state: 2` (RED). RED doesn't set itself, so an untended library reports zero debt. Use **`reviewDate`** (on every response) — anything in the past, plus anything with no review date set.
- **[Sharing & links](/docs/concepts/sharing-and-links):** noted that opening a share link rewrites to a `/guest/` route carrying the alias, and that **the section segment isn't validated** — a system's UUID and code under `/policies/` still renders the system, so don't infer section from the URL.

## 2026-08-07

**Client compatibility documented honestly, after an independent cross-platform test.** [Getting started](/docs/getting-started) previously implied any MCP client would work, with ChatGPT as a "same pattern" aside. That overclaimed:

- **Google Gemini CLI is verified working** — 48 tools over OAuth against a production workspace, with the exact `gemini mcp add` command now documented. Retrieval behaviour was identical to Claude's, confirming the server behaves the same regardless of client.
- **Concurrent clients verified** — Claude and Gemini CLI held live sessions on the same user simultaneously. One token can serve several clients (generating a *new* token still disconnects all of your own at once).
- **But several clients can't connect at all:** ChatGPT needs a paid tier with developer mode, and the Gemini **web app** has no custom-server option whatsoever (Gemini Enterprise or the CLI only). A new compatibility table states which clients work, and a rollout warning flags that free-tier users may have no route in.

## 2026-08-05

From a second-round external audit (Jim Carlin), both on [Sharing & links](/docs/concepts/sharing-and-links):

- **The human-readable share link is not agent-fetchable.** It's a client-rendered view, so a plain HTTP request returns the JavaScript shell rather than the document — and the 404 for a wrong share code is *also* client-side, so status codes prove nothing. Stated explicitly now, along with the consequence: with the api-host form still 403ing, **there is currently no share URL an external agent can fetch without a browser**. Share links are for people; programs should use MCP.
- **Share codes are not unique per document.** Duplicating a document copies its share code, so a copy and its original share one code (reproduced across two document pairs). Index on document UUID, not share code. Two code formats are also in circulation, so don't validate by shape. Logged with the product team.

## 2026-08-04

**Corrections from a second external field audit** (all 15 pages read and cross-checked against the live schemas and a 30-call pipeline run — thank you, Jim Carlin):

- **NEW — the human-readable share link is documented.** `https://{alias}.systemhub.com/systems/{uuid}/{shareCode}` **renders the published document in a browser with no login** (verified 4 Aug in a clean session; a wrong share code 404s). [Sharing & links](/docs/concepts/sharing-and-links) previously said no human app URL existed via the API — that was wrong, and it was steering agents away from a working answer. This is also the practical workaround for the `api.systemhub.com` 403.
- **Fixed a broken example.** [Organise the library](/docs/guides/organising-content) showed `{"parent": "root"}` on the folder-create tools. `parent` is typed as a UUID there and `"root"` is rejected — omit the field for top level. (`"root"` is valid on `get_folder_tree`, which is where it was copied from.)
- **Corrected the publish model.** [Document lifecycle](/docs/concepts/document-lifecycle) implied edits need an explicit publish. They don't — `edit_*` auto-publishes, **and so do metadata writes**: `add_document_tags` and the template/media/attachment tools default to `publish: true`. Tagging a document publishes it, which defeats a `publish: false` created earlier. There is no quiet-editing mode by default.
- **[Teach your AI](/docs/teach-your-ai)** no longer writes an ambiguous state fact into permanent agent memory ("drafts are ORANGE" collided with state 0 = GREY/draft and with `publish: false`); it now names all three senses.
- **Corrected the 126KB advice.** "Write in sections" made it worse — `edit_*` replaces the whole content field, so incremental writing resends everything each time. Split across documents instead.
- Also: `get_document_activity_log` added to the audit tool list, a warning that `manage_document_members` `update` **replaces** roles rather than merging, a pagination warning, and a corrected tool count on [Audit access](/docs/guides/auditing-access).

## 2026-07-31 (later)

- **[Getting started](/docs/getting-started) now carries a field-tested team-connection procedure**, verified live by a SYSTEMologist agency connecting a second team member: each person generates their own token from their own login, then connects through the *existing* connector entry and approves as themselves. Added troubleshooting rows for *"No active agent token found"* and *"a server with this URL already exists"*.
- **Correction:** generating a token does **not** disconnect colleagues. Tokens are per-person — generating revokes only your own previous token and your own sessions. Earlier wording here implied it was account-wide; that was wrong, and it was disproven in a live test (one member generated a token while another stayed connected throughout).

## 2026-07-31

- **Correction — MCP session scoping is workspace-level, not per-user.** These docs previously stated that a connection is scoped to the connecting user's visibility. That is **not** how the current OAuth flow behaves: a session is bound to the identity on the workspace's **most recently generated AI Gateway token**, regardless of who connects. On a multi-user workspace, agents can therefore resolve to the same identity — in either direction (a restricted user inheriting broader visibility, or an admin being scoped down). The claim has been corrected on Getting started, Errors & limits, Teach your AI and llms.txt. A fix binding each connection to the person connecting is logged as a critical item with the product team; these docs will be updated when it ships.
- Practical guidance until then: treat MCP access as **workspace-level**. Connect agents only for people you're comfortable seeing everything the token generator can see, and don't rely on MCP session identity for audit attribution.

## 2026-07-29

- **Docs now live at systemhub.com/docs** (review mode — noindex until final technical sign-off). llms.txt and llms-full.txt are served at the systemhub.com root.
- **Getting started now carries the confirmed connection details from the product UI:** server URL `https://mcp.systemhub.com/mcp`, OAuth Client ID = company alias, token shown once with a **180-day lifetime** (rotation reminder at day 144), and the gotcha that generating a new token immediately revokes the old one and disconnects connected agents (also added to troubleshooting).

## 2026-07-28

**Field-tested by a beta agency** (25-call end-to-end SOP pipeline). Two issues confirmed and documented while fixes are tracked with the product team:

- **HTML-escaped `content` is stored silently** and publishes as visible tag soup — warning added to [Authoring content](/docs/concepts/authoring-content) and the [errors table](/docs/concepts/errors-and-limits): send raw HTML, read back after writing.
- **Share links currently fail external fetch** (403 "Company not found") — [Sharing & links](/docs/concepts/sharing-and-links) updated with the known issue; don't promise external access until the fix lands.
- Also noted on Sharing & links: **no human app URL exists in any API response** today (`appUrl` is a requested enhancement).

## 2026-07-27

**Docs: machine-affordance upgrades** (patterns adopted from an audit of Outstand's docs — the headless reference standard):

- **`/llms-full.txt`** — the entire docs corpus in one fetch, generated with every build. Linked from llms.txt.
- **Canonical metadata on every raw page** — each `.md` now carries its canonical URL and a connect/auth/tool-count line, so a page quoted into an agent's context keeps its address.
- **llms.txt hardened** — dated, with a "Canonical facts" block (authoritative over stale third-party write-ups) and a "What the MCP does not do" list.
- **Getting started expanded** — per-client connection steps (Claude, ChatGPT, any MCP client) and a six-symptom troubleshooting table.
- **[Document lifecycle](/docs/concepts/document-lifecycle)** gained a "How systemHUB behaves over time" table — the create/publish/edit/editor-filter sequence an agent should reason with.
- **[Teach your AI](/docs/teach-your-ai)** — new page: the first-session prompt and the standing-context briefing an agent saves (CLAUDE.md or equivalent) so every future session can drive systemHUB without re-learning.

## 2026-07-23

**MCP: 5 new tools** (snapshot 43 → 48):

- `generate_document_share_link` — public, no-login share URLs that serve the published document as machine-readable JSON. See the new [Sharing & links](/docs/concepts/sharing-and-links) page.
- `get_document_activity_log` — per-document audit trail: who created it, who last edited it, full event feed (optionally including view events).
- `manage_document_members` — **write-side document access**: assign/remove members and roles on a document.
- `list_company_members` / `list_roles` — resolve people and roles by name to UUIDs (companions to `manage_document_members`).

**Known-limits changes** these tools unlock:

- ~~"No write-side user management"~~ → narrowed: document-level member/role **assignment is now writable**. Seat provisioning (inviting people, allocating licences) remains app-UI only.
- ~~"No who-viewed-what telemetry"~~ → narrowed: **per-document activity (including views) is now readable** via the activity log. Workspace-wide usage analytics remain unavailable.

**Docs:** added [Sharing & links](/docs/concepts/sharing-and-links) and this changelog; system anatomy in [Authoring content](/docs/concepts/authoring-content) extended to Trigger → Steps → Definition of done.

## 2026-07-22

- Initial public preview: getting started (with real AI Gateway connection steps), [quick wins](/docs/quick-wins) (8 verified prompts), four concept pages, three worked guides, and the full generated tool reference (43 tools).
- Every page dual-served as raw markdown (`.md`), curated `llms.txt` published.