Skip to content

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

Open
BYWallace wants to merge 6 commits into
mainfrom
drop-retired-docs-links
Open

BYWallace wants to merge 6 commits into
mainfrom
drop-retired-docs-links

Conversation

@BYWallace

@BYWallace BYWallace commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

Primary change type

  • Bug fix
  • Documentation
  • Feature
  • Tests
  • Dependency update
  • Maintenance or refactor

Problem and motivation

The agent quick start, authoring guide, MCP setup, call-surface, credentials, signals and workflows pages on docs.sapiom.ai were retired on 2026-10-23. Several places still sent people and agents to those pages, which now return 404:

  • the authoring skill shipped into every scaffolded project;
  • Agent Studio's system prompt, help palette and welcome screen;
  • the @sapiom/agent README.

The first-run telemetry notice also linked a /telemetry page that never existed.

Summary and scope

  • Authoring skill (packages/agent-core/skills/sapiom-agent-authoring/SKILL.md): links to retired pages removed. The result is copied verbatim to the two scaffold templates and the plugin, as skill-sync.test.ts requires.
  • Agent Studio:
    • The bundled system prompt loses its "Guide:" line, matching the text the backend serves at GET /v1/harness/system-prompt.
    • The help palette keeps only AI models, a capability page.
    • The first-run "Read documentation" link and its unused CSS are removed.
    • The prompt snapshot digest in default.test.ts moves with the prompt.
    • The help-list and footer comments are updated in their own commit.
  • @sapiom/agent README: drops the signals-guide link.
  • Telemetry notice: FIRST_RUN_NOTICE drops the /telemetry URL and keeps the opt-out variable.
  • Unchanged: /capabilities links.

Out of scope:

  • packages/mcp/src/instructions.generated.ts and the skill's authoring-rules stamp. Both snapshot what the backend serves, so they get regenerated after the backend's matching text change deploys (scripts/mcp-instructions-snapshot.mjs, scripts/authoring-rules-stamp.mjs --from-served).
  • Root docs.sapiom.ai/ links (SDK READMEs, DOCS_SITE). They still resolve.
  • Drift in the bundled Studio prompt. The prompt already differed from the backend's served copy before this change, by about 60 diff lines. The pin here snapshots the local copy and doesn't check the backend.

Related work

Related issue or discussion: SAP-4074.

Validation

pnpm --filter @sapiom/agent-core exec jest src/__tests__/skill-sync.test.ts src/__tests__/authoring-rules-stamp.test.ts — 69 passed
pnpm --filter @sapiom/analytics-core test — 242 passed
pnpm --filter @sapiom/analytics-core typecheck / lint — clean
(packages/harness) vitest run src/profiles src/server/served-system-prompt.test.ts src/core/inject/skills-plugin.test.ts web/src/lib — 1181 passed after the palette query fix
(packages/harness) pnpm typecheck / pnpm lint — clean

I didn't run the Playwright specs I edited (web/e2e/welcome.spec.ts, web/e2e/palette-search.spec.ts) locally. CI runs them.

Tests and documentation

  • Tests updated:
    • the prompt snapshot digest;
    • the legacy-claims list in default.test.ts, which drops the guide line;
    • the palette unit test query, now models;
    • two e2e specs, which now assert the remaining AI models page and that the welcome screen has no docs link.
  • Docs: the README edit above.

Compatibility and release impact

  • Breaking or externally visible changes: the removed help links, welcome link and telemetry URL no longer appear. No API changes.
  • Changeset: Added (.changeset/drop-retired-docs-links.md, patch for agent-core, agent, harness and analytics-core).

Security

  • I have not included secrets, credentials, private data, or unsanitized logs.
  • This pull request does not publicly disclose a suspected vulnerability. I
    will follow the
    Security Policy for
    private reporting.

AI assistance

  • I did not use AI assistance for this change.
  • I used AI assistance and have described it below.

Claude Code made the edits and ran the checks listed above, working from a link inventory of the affected files.

Checklist

  • I read CONTRIBUTING.md, and this contribution follows the direct-PR or issue-first policy.
  • This pull request addresses one focused problem and contains no unrelated cleanup.
  • I added or updated tests, or explained above why tests are not applicable.
  • I ran the relevant build, typecheck, lint, and test commands, or explained
    any N/A checks above.
  • I updated documentation for user-facing changes, or marked it N/A above.
  • I added a Changeset for a published-package change, or explained why it is not applicable.
  • I can explain and maintain every submitted change, including any AI-assisted work.

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Documentation
    • Removed links to retired agent-authoring, quick-start, MCP setup, call-surface, signals, and telemetry documentation.
    • The in-app documentation list now shows the AI models page; links to capability pages remain available.
  • User Interface
    • Removed the “Read documentation” link from the first-run welcome footer. The telemetry opt-in remains.
    • Updated documentation search checks to reflect the available AI models page.

@BYWallace

Copy link
Copy Markdown
Contributor Author

/devin review

@coderabbitai

coderabbitai Bot commented Oct 26, 2026 •

Copy link
Copy Markdown

Review in Change Stack →

No actionable comments were generated in the recent review.

Recent review info
Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 327cc6f0-8b1f-4d11-a78f-9e783400b2cd
Commits

Reviewing files that changed from the base of the PR and between 8c2430b and 3201bf2.

Files selected for processing: 16
  • .changeset/drop-retired-docs-links.md
  • packages/agent-core/skills/sapiom-agent-authoring/SKILL.md
  • packages/agent-core/templates/coding-pause/.claude/skills/sapiom-agent-authoring/SKILL.md
  • packages/agent-core/templates/default/.claude/skills/sapiom-agent-authoring/SKILL.md
  • packages/agent/README.md
  • packages/analytics-core/src/analytics.ts
  • packages/harness/src/profiles/default.test.ts
  • packages/harness/src/profiles/default.ts
  • packages/harness/web/e2e/palette-search.spec.ts
  • packages/harness/web/e2e/welcome.spec.ts
  • packages/harness/web/src/components/NewSessionComposer.tsx
  • packages/harness/web/src/lib/docs.ts
  • packages/harness/web/src/lib/palette.test.ts
  • packages/harness/web/src/styles.css
  • plugins/sapiom/skills/sapiom-agent-authoring/SKILL.md
  • scripts/agent-studio-terminology-allowlist.json
Files with no reviewable changes: 3
  • packages/agent/README.md
  • packages/harness/src/profiles/default.ts
  • scripts/agent-studio-terminology-allowlist.json

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

Walkthrough

This change removes links to retired documentation pages from agent-authoring guidance, harness documentation surfaces, the default system prompt, and package text. The harness documentation list retains the AI models page. Capabilities references remain in the agent-authoring guidance.

Changes: Retired documentation links

Layer / File(s) Summary
Agent-authoring references
packages/agent-core/skills/sapiom-agent-authoring/SKILL.md, packages/agent-core/templates/*/.claude/skills/sapiom-agent-authoring/SKILL.md, plugins/sapiom/skills/sapiom-agent-authoring/SKILL.md
Removes links to retired MCP setup, credentials and configuration, and call-surface pages. The capabilities references remain.
Harness documentation surfaces
packages/harness/web/src/lib/docs.ts, packages/harness/web/src/components/NewSessionComposer.tsx, packages/harness/web/src/styles.css, packages/harness/web/e2e/*, packages/harness/web/src/lib/palette.test.ts, scripts/agent-studio-terminology-allowlist.json
The documentation list retains the AI models page. The first-run footer loses its documentation link. Related tests, styles, and the terminology allowlist are updated.
Package notices and prompt
.changeset/drop-retired-docs-links.md, packages/agent/README.md, packages/analytics-core/src/analytics.ts, packages/harness/src/profiles/default.ts, packages/harness/src/profiles/default.test.ts
Removes the “Using signals” link, the telemetry documentation URL, and the call-surface guide URL from the default prompt. Updates the prompt digest and related test claims. The changeset records patch releases for four packages.

Priority: Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix

Suggested reviewers: gwitwer

Merge Risk: Minimal · up to 3201b

The documentation-link removals are consistent with the stated retirement changes and are ready to merge.

Pre-merge checks: Passed 4 · Failed 1

Failed Failed checks: 1 warning

Check name Status Explanation Resolution
Docstring Coverage Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 7 files. (6 skipped: 6 … Write docstrings for the functions missing them to satisfy the coverage threshold.
Passed Passed checks: 4 passed
Check name Status Explanation
Title check Passed The title clearly and concisely describes the primary change: removing links to retired documentation pages.
Description check Passed The description follows the required template, explains the problem and scope, documents validation and test coverage, identifies the unrun Playwright tests, records release impact and the changeset, …
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Description check

Explanation

The description follows the required template, explains the problem and scope, documents validation and test coverage, identifies the unrun Playwright tests, records release impact and the changeset, and completes the security, AI assistance, and checklist sections.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 7 files. (6 skipped: 6 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

Finishing Touches: 💡 1
📝 Generate docstrings: 💡
  • Commit to this branch
  • Create a new PR
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

A rabbit hops through pages gone,
The retired links have all moved on.
AI models stay in view,
Capabilities remain there too.
I nibble clover, pleased and spry.

Comment @coderabbitai help to get the list of available commands.

@devin-ai-integration

Copy link
Copy Markdown
Contributor

Starting Devin Review.

Devin Review

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

Devin Review

BYWallace and others added 5 commits October 26, 2026 16:30
The skill and its three synced copies linked the MCP setup,
credentials, call-surface, authoring-guide and quick-start pages of
docs.sapiom.ai, which were retired. The /capabilities links stay.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The bundled system prompt's call-surface guide line, four of the five
help-palette pages (agents and workflows quick starts, both MCP setup
pages) and the first-run "Read documentation" link all pointed at docs
pages that no longer exist. The palette keeps AI models, a capability
page. The prompt snapshot digest moves with the prompt.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The @sapiom/agent README linked a signals guide that is gone, and the
first-run telemetry notice linked a /telemetry page that never existed.
The notice still names the opt-out variable.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The comments explained a five-page help list and a footer with a docs
link. After the retired pages came out they describe one page and no
link, so they now say what remains and why the rest went. Kept apart
from the link removal because it changes what the comments claim.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@BYWallace
BYWallace force-pushed the drop-retired-docs-links branch from 8d2b20f to 3350faa Compare October 26, 2026 23:34
The help palette no longer lists the workflows quick start, so the
allowlist entry for its title and URL matched nothing and failed
`pnpm terminology:check`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@BYWallace

Copy link
Copy Markdown
Contributor Author

/devin review

@devin-ai-integration

Copy link
Copy Markdown
Contributor

Starting Devin Review.

Devin Review

@BYWallace
BYWallace marked this pull request as ready for review October 27, 2026 00:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant