[DRAFT] New docs

[quietbits]

Important

Apache-specific affordances — The Link response headers (RFC 8288) and Accept-based markdown content negotiation are implemented in public/.htaccess using mod_rewrite and mod_headers. They only take effect on Apache hosts. On GitHub Pages, Cloudflare Pages, Netlify, and any other host that doesn't honor .htaccess, those features silently degrade to the URL-.md convention only (no errors, just no Link header and no content negotiation). If we move the docs to a non-Apache host, the same behaviors need to be re-expressed in that host's native format (_headers file, edge function, etc.).

Note

Deploy target is stellar.github.io/js-stellar-sdk — config/site.ts is the single source of truth: SITE_URL = "https://stellar.github.io", BASE_PATH = "/js-stellar-sdk". All generated artifacts (docs/llms.txt, docs/llms-full.txt, public/robots.txt, public/.htaccess, and the Astro sitemap) reference those values. To retarget to a different host or sub-path, edit config/site.ts and run pnpm docs.

Warning

No auto-deploy workflow — docs_build.yml builds and diff-checks the docs on every PR but does not push to any host. Whoever owns docs publishing needs to wire up a follow-up workflow (or update an existing one) that uploads dist/site/ after a master push. Deferred from this PR by design.

Note

Generated artifacts are gitignored — public/robots.txt, public/llms.txt, public/llms-full.txt, and public/.htaccess are produced on every build and not committed. Reviewers should run pnpm docs locally to inspect the deployed output; the source-tree diff alone does not show them.

Summary

• New Astro/Starlight docs site replacing the legacy JSDoc pipeline: Adds astro.config.mjs, docs/ content collection, src/content.config.ts, and a Starlight PageTitle component override (suppresses a duplicate H1 from frontmatter; preserves the SkipLink target). Retires the old website/ scripts and bundle-publish workflow.

• TypeDoc-driven reference generator (build-docs.ts): Parses every exported SDK symbol via TypeDoc, buckets them by source-file path into named groups ("Core / Keys", "Network / Horizon", "SEPs / WebAuth", etc.), and renders one markdown page per bucket with title + description frontmatter. Source links pin to an evergreen ref so generated pages don't churn on every commit.

• Source-wide TSDoc migration: Every module (horizon, rpc, webauth, base, stellartoml, contract, utils, index) had its JSDoc-flavored comments converted to TSDoc. Removed @constant, @default, @memberof, @class, @enum, @typedef, @hideconstructor, @static; converted @param {Type} name desc to @param name - desc (types come from signatures); replaced @throws {Error} with @throws; wrapped @example snippets in fenced code blocks. Comment-only changes — no runtime behavior change.

• Single-source-of-truth deploy config (config/site.ts): Centralizes SITE_URL, BASE_PATH, SITE_BASE_URL, AI_POLICY (Cloudflare Content Signals), and ALLOWED_AI_BOTS. Consumed by astro.config.mjs, build-robots.ts, and build-htaccess.ts so a single edit retargets the entire site to a new host or base path.

• LLMs bundles + README→index sync (build-llms.ts): Emits docs/llms.txt (compact routing-map index) and docs/llms-full.txt (full corpus + appended CHANGELOG.md) with bundle-relative URLs so the bundles resolve correctly on any host or sub-path. Also syncs README.md → docs/index.md (frontmatter prepended, title derived from README's H1) so the GitHub README and the docs homepage are one source.

• Agent-readiness server config (build-robots.ts + build-htaccess.ts): Generates a robots.txt carrying explicit per-bot Allow rules for major AI crawlers and Cloudflare Content Signals (search, ai-input, ai-train). Generates an Apache .htaccess advertising the LLMs bundles via RFC 8288 Link response headers and implementing Accept-based markdown content negotiation. Files inert on hosts that don't honor .htaccess.

• Raw markdown siblings (build-md-siblings.ts): Copies every docs page to a URL.md sibling in the build output so agents can fetch the raw markdown by appending .md to any rendered URL. Rewrites relative non-.md link targets (drops one leading ../) so internal links resolve correctly in both the HTML and raw-.md URL spaces, regardless of deployment base path.

• agents.md page + sidebar entry: New "AI Agents" docs page describing all three agent-facing surfaces (bundles, raw markdown, crawler policy) and explicitly listing the agent-readiness conventions deliberately not implemented for a JS SDK doc site (RFC 9727 API catalog, MCP server card, OAuth discovery, A2A agent card, commerce protocols).

• Docs build CI (docs_build.yml): New PR-time workflow chaining docs:reference → docs:llms → docs:robots → docs:htaccess → docs:site and diff-checking docs/ for drift between generated and committed content. CONTRIBUTING refreshed to point at the new docs guide.

[socket-security]

Warning

Review the following alerts detected in dependencies.

According to your organization's Security Policy, it is recommended to resolve "Warn" alerts. Learn more about Socket for GitHub.

Action	Severity	Alert  (click "▶" to expand/collapse)
Warn		License policy violation: npm @img/sharp-libvips-darwin-arm64 under LGPL-3.0-or-later Location: Package overview From: pnpm-lock.yaml → npm/astro@6.3.0 → npm/@img/sharp-libvips-darwin-arm64@1.2.4 ℹ Read more on: This package | This alert | What is a license policy violation? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Find a package that does not violate your license policy or adjust your policy to allow this package's license. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/@img/sharp-libvips-darwin-arm64@1.2.4. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		License policy violation: npm @img/sharp-libvips-darwin-x64 under LGPL-3.0-or-later Location: Package overview From: pnpm-lock.yaml → npm/astro@6.3.0 → npm/@img/sharp-libvips-darwin-x64@1.2.4 ℹ Read more on: This package | This alert | What is a license policy violation? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Find a package that does not violate your license policy or adjust your policy to allow this package's license. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/@img/sharp-libvips-darwin-x64@1.2.4. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		License policy violation: npm @img/sharp-libvips-linux-arm under LGPL-3.0-or-later Location: Package overview From: pnpm-lock.yaml → npm/astro@6.3.0 → npm/@img/sharp-libvips-linux-arm@1.2.4 ℹ Read more on: This package | This alert | What is a license policy violation? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Find a package that does not violate your license policy or adjust your policy to allow this package's license. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/@img/sharp-libvips-linux-arm@1.2.4. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		License policy violation: npm @img/sharp-libvips-linux-arm64 under LGPL-3.0-or-later Location: Package overview From: pnpm-lock.yaml → npm/astro@6.3.0 → npm/@img/sharp-libvips-linux-arm64@1.2.4 ℹ Read more on: This package | This alert | What is a license policy violation? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Find a package that does not violate your license policy or adjust your policy to allow this package's license. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/@img/sharp-libvips-linux-arm64@1.2.4. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		License policy violation: npm @img/sharp-libvips-linux-ppc64 under LGPL-3.0-or-later Location: Package overview From: pnpm-lock.yaml → npm/astro@6.3.0 → npm/@img/sharp-libvips-linux-ppc64@1.2.4 ℹ Read more on: This package | This alert | What is a license policy violation? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Find a package that does not violate your license policy or adjust your policy to allow this package's license. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/@img/sharp-libvips-linux-ppc64@1.2.4. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		License policy violation: npm @img/sharp-libvips-linux-riscv64 under LGPL-3.0-or-later Location: Package overview From: pnpm-lock.yaml → npm/astro@6.3.0 → npm/@img/sharp-libvips-linux-riscv64@1.2.4 ℹ Read more on: This package | This alert | What is a license policy violation? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Find a package that does not violate your license policy or adjust your policy to allow this package's license. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/@img/sharp-libvips-linux-riscv64@1.2.4. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		License policy violation: npm @img/sharp-libvips-linux-s390x under LGPL-3.0-or-later Location: Package overview From: pnpm-lock.yaml → npm/astro@6.3.0 → npm/@img/sharp-libvips-linux-s390x@1.2.4 ℹ Read more on: This package | This alert | What is a license policy violation? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Find a package that does not violate your license policy or adjust your policy to allow this package's license. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/@img/sharp-libvips-linux-s390x@1.2.4. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		License policy violation: npm @img/sharp-libvips-linux-x64 under LGPL-3.0-or-later Location: Package overview From: pnpm-lock.yaml → npm/astro@6.3.0 → npm/@img/sharp-libvips-linux-x64@1.2.4 ℹ Read more on: This package | This alert | What is a license policy violation? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Find a package that does not violate your license policy or adjust your policy to allow this package's license. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/@img/sharp-libvips-linux-x64@1.2.4. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		License policy violation: npm @img/sharp-libvips-linuxmusl-arm64 under LGPL-3.0-or-later Location: Package overview From: pnpm-lock.yaml → npm/astro@6.3.0 → npm/@img/sharp-libvips-linuxmusl-arm64@1.2.4 ℹ Read more on: This package | This alert | What is a license policy violation? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Find a package that does not violate your license policy or adjust your policy to allow this package's license. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/@img/sharp-libvips-linuxmusl-arm64@1.2.4. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		License policy violation: npm @img/sharp-libvips-linuxmusl-x64 under LGPL-3.0-or-later Location: Package overview From: pnpm-lock.yaml → npm/astro@6.3.0 → npm/@img/sharp-libvips-linuxmusl-x64@1.2.4 ℹ Read more on: This package | This alert | What is a license policy violation? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Find a package that does not violate your license policy or adjust your policy to allow this package's license. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/@img/sharp-libvips-linuxmusl-x64@1.2.4. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		License policy violation: npm @img/sharp-wasm32 Location: Package overview From: pnpm-lock.yaml → npm/astro@6.3.0 → npm/@img/sharp-wasm32@0.34.5 ℹ Read more on: This package | This alert | What is a license policy violation? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Find a package that does not violate your license policy or adjust your policy to allow this package's license. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/@img/sharp-wasm32@0.34.5. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		License policy violation: npm @img/sharp-win32-arm64 Location: Package overview From: pnpm-lock.yaml → npm/astro@6.3.0 → npm/@img/sharp-win32-arm64@0.34.5 ℹ Read more on: This package | This alert | What is a license policy violation? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Find a package that does not violate your license policy or adjust your policy to allow this package's license. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/@img/sharp-win32-arm64@0.34.5. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		License policy violation: npm @img/sharp-win32-ia32 Location: Package overview From: pnpm-lock.yaml → npm/astro@6.3.0 → npm/@img/sharp-win32-ia32@0.34.5 ℹ Read more on: This package | This alert | What is a license policy violation? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Find a package that does not violate your license policy or adjust your policy to allow this package's license. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/@img/sharp-win32-ia32@0.34.5. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		License policy violation: npm @img/sharp-win32-x64 Location: Package overview From: pnpm-lock.yaml → npm/astro@6.3.0 → npm/@img/sharp-win32-x64@0.34.5 ℹ Read more on: This package | This alert | What is a license policy violation? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Find a package that does not violate your license policy or adjust your policy to allow this package's license. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/@img/sharp-win32-x64@0.34.5. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		High CVE: Svelte npm devalue: DoS via sparse array deserialization CVE: GHSA-77vg-94rm-hx3p Svelte devalue: DoS via sparse array deserialization (HIGH) Affected versions: >= 5.6.3 < 5.8.1 Patched version: 5.8.1 From: pnpm-lock.yaml → npm/astro@6.3.0 → npm/devalue@5.8.0 ℹ Read more on: This package | This alert | What is a CVE? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Remove or replace dependencies that include known high severity CVEs. Consumers can use dependency overrides or npm audit fix --force to remove vulnerable dependencies. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/devalue@5.8.0. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

View full report

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	tsx@​4.21.0
	@​astrojs/​sitemap@​3.7.2
	@​astrojs/​starlight@​0.39.0
	eslint-plugin-tsdoc@​0.5.2
	astro@​6.3.0
	typedoc@​0.28.19

View full report