Skip to content

docs: pin canonical AIsa skill.md and current credential guidance - #105

Draft
eddiearc wants to merge 2 commits into
mainfrom
docs/aisa-discovery-fix-20260914
Draft

eddiearc wants to merge 2 commits into
mainfrom
docs/aisa-discovery-fix-20260914

Conversation

@eddiearc

@eddiearc eddiearc commented Sep 14, 2026

Copy link
Copy Markdown
Contributor

Agents discovering AIsa through Mintlify previously received an automatically generated REST Skill that contradicted the canonical CLI/MCP Skill. A repo-root skill.md now uses Mintlify's supported override and is exported from the immutable canonical Skill commit e780949. One documented transformation rewrites its relative LICENSE link to the same commit's public LICENSE URL.

A focused offline export check runs in PR/main CI, including a mutated-export negative control. It verifies the pinned export; future canonical changes still require an intentional pin/export update. It does not silently track upstream main.

English/Chinese Quickstart and fallback guidance now match the existing CLI credential model. CLI-managed OAuth is not presented as a static key for raw HTTP; direct HTTP requires a separately configured static key/authorized secret. User-facing release chatter is removed, and the paid-approval XML remains unchanged.

Native discovery configuration

Both existing API Reference tabs now declare openapi: "openapi.yaml", the documented Mintlify ingestion input. Removing only these two keys produces the previous navigation tree exactly. Official validateDocsConfig accepts both configurations without warnings.

This is a source configuration change, not a claim that the hosted api-catalog404 is already fixed. Local mint dev also404s known hosted AgentCard/OpenAPI resources, so it cannot certify the hosted metadata endpoint. No same-snapshot runtime sidebar comparison was performed; navigation evidence is structural. The discovery guide gives working OpenAPI/documentation index fallbacks until hosted verification passes.

Validation and release order

  • Offline export check, adjacent canonical-source comparison, and mutated-export rejection passed; PR CI passed.
  • Existing EN/ZH page/group ordering is unchanged, and official config validation passed.
  • Existing slug validation failures outside the edited files remain pre-existing; no unrelated API pages were renamed.
  • Merge Skill #53 before this PR. CLI #27 requires its normal release for new help to reach npm users.
  • After Docs publication and Mintlify regeneration, compare automatic Skill/index content with the pinned export and require HTTP200 plus a valid catalog body at both https://aisa.one/docs/.well-known/api-catalog and https://aisa.mintlify.dev/docs/.well-known/api-catalog. Generation may take up to24h. If the catalog remains404, retain the explicit fallback and investigate the hosted platform response.
  • No proxy, permission change, OAuth login, paid call or production deployment was performed in this PR.

Companions: landing #108 and domain MCP #5.

eddiearc and others added 2 commits September 14, 2026 22:05
Mintlify root skill.md overrides the auto REST skill from Skill e780949; LICENSE is inlined.

Co-authored-by: Cursor <cursoragent@cursor.com>
Rewrite the relative LICENSE link to the pinned raw GitHub URL instead of
inlining MIT text. Keep static-key HTTP fallbacks, honest catalog 404s, and
an offline export --check in CI.

Co-authored-by: Cursor <cursoragent@cursor.com>
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