fix: drop links to retired docs.sapiom.ai pages [SAP-4074]

.changeset/drop-retired-docs-links.md

@@ -0,0 +1,8 @@
+---
+"@sapiom/agent-core": patch
+"@sapiom/agent": patch
+"@sapiom/harness": patch
+"@sapiom/analytics-core": patch
+---
+
+Stop linking docs.sapiom.ai pages that no longer exist. The `sapiom-agent-authoring` skill and its scaffold copies, the Agent Studio system prompt, help palette and welcome screen, and the `@sapiom/agent` README drop links to the agent quick start, authoring guide, MCP setup, call-surface, credentials and signals guides. The first-run telemetry notice drops its link to a `/telemetry` page that never existed. Links to `/capabilities` pages are unchanged.

packages/agent-core/skills/sapiom-agent-authoring/SKILL.md

@@ -51,8 +51,7 @@ first:
 claude mcp add sapiom -- npx -y @sapiom/mcp
 ```
 
-Other clients: run `npx -y @sapiom/mcp` as a local (stdio) MCP server — see
-[docs.sapiom.ai](https://docs.sapiom.ai/integration/mcp-servers/setup) for per-client config.
+Other clients: run `npx -y @sapiom/mcp` as a local (stdio) MCP server.
 Sapiom's other server, **the hosted capability server** (`https://api.sapiom.ai/v1/mcp`), is
 for a one-off call with no automation to keep; which server a task belongs to, and what local
 work does and does not spend, is the served section
@@ -323,8 +322,7 @@ Database lifetime and metering: served section
 ### Secrets, `agents.launch`, receipts, App Link webhooks
 
 Taught once, in the served text — not restated here. Per-agent secrets and the read-only Vault:
-[Capabilities from steps](https://api.sapiom.ai/v1/agents/authoring-rules#capability-catalog) and
-[Credentials and configuration](https://docs.sapiom.ai/reference/credentials-and-configuration).
+[Capabilities from steps](https://api.sapiom.ai/v1/agents/authoring-rules#capability-catalog).
 Fire-and-forget dispatch with `ctx.sapiom.agents.launch`: "Composing Deployed Agents" below and
 [Composing deployed agents](https://api.sapiom.ai/v1/agents/authoring-rules#agent-composition).
 Receipts and manual replay of inbound events: the local authoring server's served primer (in
@@ -410,8 +408,7 @@ The full rule — the worked example (`llm.run` with `output`, read back with `s
 as output, the label rule and the result's `servedClass`/`lane` disclosure, and how to debug a
 run in the Run Inspector — is the served section
 [Calling LLMs from steps](https://api.sapiom.ai/v1/agents/authoring-rules#llm-call-surface).
-Read it before the first `llm.*` / `models.run` / `agents.run` call. Customer guide:
-[Choose a call surface](https://docs.sapiom.ai/guides/choose-a-call-surface).
+Read it before the first `llm.*` / `models.run` / `agents.run` call.
 
 <!-- /section: llm-call-surface -->
 
@@ -739,8 +736,5 @@ Write each step the way it should run in production — never weaken logic to sh
 | Resource                                                                     | What it covers                                                                                                 |
 | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
 | [Platform rules (served)](https://api.sapiom.ai/v1/agents/authoring-rules)   | The live text every platform chapter above summarizes and points at; this copy was written against release 1.1 |
-| [Authoring guide](https://docs.sapiom.ai/agents/authoring)                   | Full step model, failure patterns, pause/resume, determinism                                                   |
-| [Quickstart](https://docs.sapiom.ai/agents/quick-start)                      | Scaffold → write → test → deploy walkthrough                                                                   |
 | [Capabilities](https://docs.sapiom.ai/capabilities)                          | The full `ctx.sapiom.*` catalog with pricing                                                                   |
-| [Choose a call surface](https://docs.sapiom.ai/guides/choose-a-call-surface) | `llm.run` vs `models.run` vs `agents.run` — which to call and why                                              |
 | `AGENTS.md` in your scaffold                                                 | The quick in-project reference                                                                                 |

packages/agent-core/templates/coding-pause/.claude/skills/sapiom-agent-authoring/SKILL.md

@@ -51,8 +51,7 @@ first:
 claude mcp add sapiom -- npx -y @sapiom/mcp
 ```
 
-Other clients: run `npx -y @sapiom/mcp` as a local (stdio) MCP server — see
-[docs.sapiom.ai](https://docs.sapiom.ai/integration/mcp-servers/setup) for per-client config.
+Other clients: run `npx -y @sapiom/mcp` as a local (stdio) MCP server.
 Sapiom's other server, **the hosted capability server** (`https://api.sapiom.ai/v1/mcp`), is
 for a one-off call with no automation to keep; which server a task belongs to, and what local
 work does and does not spend, is the served section
@@ -323,8 +322,7 @@ Database lifetime and metering: served section
 ### Secrets, `agents.launch`, receipts, App Link webhooks
 
 Taught once, in the served text — not restated here. Per-agent secrets and the read-only Vault:
-[Capabilities from steps](https://api.sapiom.ai/v1/agents/authoring-rules#capability-catalog) and
-[Credentials and configuration](https://docs.sapiom.ai/reference/credentials-and-configuration).
+[Capabilities from steps](https://api.sapiom.ai/v1/agents/authoring-rules#capability-catalog).
 Fire-and-forget dispatch with `ctx.sapiom.agents.launch`: "Composing Deployed Agents" below and
 [Composing deployed agents](https://api.sapiom.ai/v1/agents/authoring-rules#agent-composition).
 Receipts and manual replay of inbound events: the local authoring server's served primer (in
@@ -410,8 +408,7 @@ The full rule — the worked example (`llm.run` with `output`, read back with `s
 as output, the label rule and the result's `servedClass`/`lane` disclosure, and how to debug a
 run in the Run Inspector — is the served section
 [Calling LLMs from steps](https://api.sapiom.ai/v1/agents/authoring-rules#llm-call-surface).
-Read it before the first `llm.*` / `models.run` / `agents.run` call. Customer guide:
-[Choose a call surface](https://docs.sapiom.ai/guides/choose-a-call-surface).
+Read it before the first `llm.*` / `models.run` / `agents.run` call.
 
 <!-- /section: llm-call-surface -->
 
@@ -739,8 +736,5 @@ Write each step the way it should run in production — never weaken logic to sh
 | Resource                                                                     | What it covers                                                                                                 |
 | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
 | [Platform rules (served)](https://api.sapiom.ai/v1/agents/authoring-rules)   | The live text every platform chapter above summarizes and points at; this copy was written against release 1.1 |
-| [Authoring guide](https://docs.sapiom.ai/agents/authoring)                   | Full step model, failure patterns, pause/resume, determinism                                                   |
-| [Quickstart](https://docs.sapiom.ai/agents/quick-start)                      | Scaffold → write → test → deploy walkthrough                                                                   |
 | [Capabilities](https://docs.sapiom.ai/capabilities)                          | The full `ctx.sapiom.*` catalog with pricing                                                                   |
-| [Choose a call surface](https://docs.sapiom.ai/guides/choose-a-call-surface) | `llm.run` vs `models.run` vs `agents.run` — which to call and why                                              |
 | `AGENTS.md` in your scaffold                                                 | The quick in-project reference                                                                                 |

packages/agent-core/templates/default/.claude/skills/sapiom-agent-authoring/SKILL.md

@@ -51,8 +51,7 @@ first:
 claude mcp add sapiom -- npx -y @sapiom/mcp
 ```
 
-Other clients: run `npx -y @sapiom/mcp` as a local (stdio) MCP server — see
-[docs.sapiom.ai](https://docs.sapiom.ai/integration/mcp-servers/setup) for per-client config.
+Other clients: run `npx -y @sapiom/mcp` as a local (stdio) MCP server.
 Sapiom's other server, **the hosted capability server** (`https://api.sapiom.ai/v1/mcp`), is
 for a one-off call with no automation to keep; which server a task belongs to, and what local
 work does and does not spend, is the served section
@@ -323,8 +322,7 @@ Database lifetime and metering: served section
 ### Secrets, `agents.launch`, receipts, App Link webhooks
 
 Taught once, in the served text — not restated here. Per-agent secrets and the read-only Vault:
-[Capabilities from steps](https://api.sapiom.ai/v1/agents/authoring-rules#capability-catalog) and
-[Credentials and configuration](https://docs.sapiom.ai/reference/credentials-and-configuration).
+[Capabilities from steps](https://api.sapiom.ai/v1/agents/authoring-rules#capability-catalog).
 Fire-and-forget dispatch with `ctx.sapiom.agents.launch`: "Composing Deployed Agents" below and
 [Composing deployed agents](https://api.sapiom.ai/v1/agents/authoring-rules#agent-composition).
 Receipts and manual replay of inbound events: the local authoring server's served primer (in
@@ -410,8 +408,7 @@ The full rule — the worked example (`llm.run` with `output`, read back with `s
 as output, the label rule and the result's `servedClass`/`lane` disclosure, and how to debug a
 run in the Run Inspector — is the served section
 [Calling LLMs from steps](https://api.sapiom.ai/v1/agents/authoring-rules#llm-call-surface).
-Read it before the first `llm.*` / `models.run` / `agents.run` call. Customer guide:
-[Choose a call surface](https://docs.sapiom.ai/guides/choose-a-call-surface).
+Read it before the first `llm.*` / `models.run` / `agents.run` call.
 
 <!-- /section: llm-call-surface -->
 
@@ -739,8 +736,5 @@ Write each step the way it should run in production — never weaken logic to sh
 | Resource                                                                     | What it covers                                                                                                 |
 | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
 | [Platform rules (served)](https://api.sapiom.ai/v1/agents/authoring-rules)   | The live text every platform chapter above summarizes and points at; this copy was written against release 1.1 |
-| [Authoring guide](https://docs.sapiom.ai/agents/authoring)                   | Full step model, failure patterns, pause/resume, determinism                                                   |
-| [Quickstart](https://docs.sapiom.ai/agents/quick-start)                      | Scaffold → write → test → deploy walkthrough                                                                   |
 | [Capabilities](https://docs.sapiom.ai/capabilities)                          | The full `ctx.sapiom.*` catalog with pricing                                                                   |
-| [Choose a call surface](https://docs.sapiom.ai/guides/choose-a-call-surface) | `llm.run` vs `models.run` vs `agents.run` — which to call and why                                              |
 | `AGENTS.md` in your scaffold                                                 | The quick in-project reference                                                                                 |

packages/agent/README.md

@@ -296,5 +296,3 @@ Three things worth knowing rather than assuming:
   the pair, so that id need not be the only run that resumes. `matched` counts
   the runs that actually resumed, which under-reports a partial fanout — read
   `message` whenever it is present.
-
-Full guide: [Using signals](https://docs.sapiom.ai/guides/use-signals).

packages/analytics-core/src/analytics.ts

@@ -15,7 +15,7 @@ import type {
 /** Printed to stderr once per machine, on the first-ever tracked event. */
 export const FIRST_RUN_NOTICE =
   "Sapiom collects anonymous usage analytics to improve the SDK. " +
-  "Opt out: SAPIOM_TELEMETRY_DISABLED=1 (https://docs.sapiom.ai/telemetry)";
+  "Opt out: SAPIOM_TELEMETRY_DISABLED=1";
 
 let processSessionId: string | null = null;
 

packages/harness/src/profiles/default.test.ts

@@ -12,7 +12,7 @@ const sha256 = (content: string) =>
  * the copy it serves, so the two move together — see the drift-guard test below.
  */
 const PINNED_PROMPT_DIGEST =
-  "a4a13da1ea4d960df634dd2946aef953a79bf6cae91907494cd6cbefc1db547a";
+  "2158c2c45db76fc9a35f20f41a888cbdaf58bc393c751bf37360d807fc55199c";
 
 const legacy = readFileSync(
   new URL("./fixtures/legacy-system-prompt.md", import.meta.url),
@@ -128,7 +128,6 @@ describe("known served-prompt compatibility", () => {
       "Structured output = tool-use/schema output",
       "**Omit `model` entirely**",
       "Raw provider ids are never\nhonored",
-      "Guide: https://docs.sapiom.ai/guides/choose-a-call-surface.",
     ]) {
       expect(legacy).toContain(claim);
       expect(DEFAULT_SYSTEM_PROMPT).toContain(claim);

packages/harness/src/profiles/default.ts

@@ -51,7 +51,6 @@ nothing. Reach for \`small\`/\`medium\`/\`large\` only to choose a class
 deliberately. Raw provider ids are never
 honored. Results disclose the served class + lane. Debugging a run: the
 Run Inspector, or the per-step I/O endpoint documented in the guide.
-Guide: https://docs.sapiom.ai/guides/choose-a-call-surface.
 
 Fixed answer set and you need a probability → \`ctx.sapiom.decisions.evaluate\` (yes/no, pick-one,
 rubric score from a System One decision model). Ask all independent questions over the same state

packages/harness/web/e2e/palette-search.spec.ts

@@ -111,12 +111,13 @@ test("the Docs tab searches the doc links and offers the docs site in the footer
   await page.getByTestId("command-palette-filter-docs").click();
 
   const list = page.getByTestId("command-palette-list");
-  await expect(list.getByText("Agents quick start")).toBeVisible();
+  await expect(list.getByText("AI models")).toBeVisible();
   await expect(page.getByTestId("command-palette-destination")).toContainText("Open documentation");
 
+  await page.getByTestId("command-palette-input").fill("models");
+  await expect(list.getByText("AI models")).toBeVisible();
   await page.getByTestId("command-palette-input").fill("mcp");
-  await expect(list.getByText("MCP servers: setup")).toBeVisible();
-  await expect(list.getByText("Agents quick start")).toBeHidden();
+  await expect(list.getByText("AI models")).toBeHidden();
 });
 
 test("a scoped tab never leaks other kinds into the results", async ({ page }) => {

packages/harness/web/e2e/welcome.spec.ts

@@ -67,11 +67,8 @@ test.describe("first run", () => {
     await expect(page.locator(".composer-template-card").first()).toBeVisible();
     await expect(page.getByTestId("composer-browse-templates")).toBeVisible();
 
-    // First-run only: the one-time telemetry opt-in (SAP-1988) and docs.
+    // First-run only: the one-time telemetry opt-in (SAP-1988).
     await expect(page.getByTestId("welcome-consent")).toBeVisible();
-    const docs = page.getByTestId("welcome-docs");
-    await expect(docs).toHaveAttribute("href", "https://docs.sapiom.ai/agents/quick-start");
-    await expect(docs).toHaveAttribute("target", "_blank");
 
     await page.screenshot({ path: "web/e2e/screenshots/composer-home.png", fullPage: true });
   });

packages/harness/web/src/components/NewSessionComposer.tsx

@@ -93,7 +93,8 @@ interface NewSessionComposerProps {
   entries: HarnessEntry[];
   onHarnessChange: (harness: HarnessKind) => void;
   /** Genuine first run (AppState.firstRun): shows the one-time telemetry
-   *  opt-in + docs footer. */
+   *  opt-in footer. The docs link it also carried pointed at a page retired
+   *  on 2026-10-23. */
   firstRun: boolean;
   /**
    * Create the agent from this idea and open its first session. Rejects with
@@ -697,15 +698,6 @@ export function NewSessionComposer({
               default; change it anytime in Settings.
             </span>
           </label>
-          <a
-            className="composer-docs"
-            data-testid="welcome-docs"
-            href="https://docs.sapiom.ai/agents/quick-start"
-            target="_blank"
-            rel="noopener noreferrer"
-          >
-            Read documentation <Icon name="ArrowUpRight" size={12} />
-          </a>
         </div>
       )}
     </div>

packages/harness/web/src/lib/docs.ts

@@ -1,11 +1,11 @@
 /**
  * The documentation the finder can reach.
  *
- * Five pages, not a mirror of the site's nav: these are the ones someone
- * reaches for from inside the product — how to start an agent, how to start a
- * workflow, which models a capability can call, and the two halves of MCP
- * setup. Everything else is one click away behind the footer link, which is
- * why this list gets to stay short instead of growing a page per release.
+ * One page, not a mirror of the site's nav: which models a capability can
+ * call. The list also held the agents and workflows quick starts and the two
+ * halves of MCP setup until those pages were retired (2026-10-23).
+ * Everything else is one click away behind the footer link, which is why this
+ * list gets to stay short instead of growing a page per release.
  */
 export const DOCS_SITE = "https://docs.sapiom.ai/";
 
@@ -18,29 +18,9 @@ export interface DocLink {
 }
 
 export const DOC_LINKS: readonly DocLink[] = [
-  {
-    label: "Agents quick start",
-    meta: "Run your first agent",
-    href: "https://docs.sapiom.ai/agents/quick-start",
-  },
-  {
-    label: "Workflows quick start",
-    meta: "Typed steps, gates and exits",
-    href: "https://docs.sapiom.ai/workflows/quick-start",
-  },
   {
     label: "AI models",
     meta: "Which models a capability can call",
     href: "https://docs.sapiom.ai/capabilities/ai-models",
   },
-  {
-    label: "MCP servers: setup",
-    meta: "Connect a server to a workspace",
-    href: "https://docs.sapiom.ai/integration/mcp-servers/setup",
-  },
-  {
-    label: "MCP servers: remote",
-    meta: "Reach a server you do not host",
-    href: "https://docs.sapiom.ai/integration/mcp-servers/remote",
-  },
 ];

packages/harness/web/src/lib/palette.test.ts

@@ -350,7 +350,7 @@ describe("rankPaletteItems filters", () => {
   it("the Docs tab lists the doc links and matches within them", () => {
     const unqueried = rank("", filterSources, "docs");
     expect(unqueried.every((item) => item.kind === "doc")).toBe(true);
-    const queried = rank("mcp", filterSources, "docs");
+    const queried = rank("models", filterSources, "docs");
     expect(queried.length).toBeGreaterThan(0);
     expect(queried.every((item) => item.kind === "doc")).toBe(true);
   });

packages/harness/web/src/styles.css

@@ -9177,7 +9177,7 @@ button.rail-footer-card:hover {
   color: var(--text-faint);
 }
 
-/* First-run footer: the one-time telemetry opt-in + docs link. */
+/* First-run footer: the one-time telemetry opt-in. */
 .composer-footer {
   width: 100%;
   max-width: 640px;
@@ -9199,17 +9199,6 @@ button.rail-footer-card:hover {
   color: var(--text-faint);
   line-height: 1.5;
 }
-.composer-docs {
-  display: inline-flex;
-  align-items: center;
-  gap: var(--sp1);
-  color: var(--text-dim);
-  font-size: var(--type-label);
-  text-decoration: none;
-}
-.composer-docs:hover {
-  color: var(--text);
-}
 /* ── Overview: a CARD ON TOP that introduces the app ──────────────────────
    Summoned from the account menu. An app-level overlay fixed over the WHOLE
    shell (rail, terminal, canvas), centred on a scrim, so re-reading what