[DRAFT] New docs

.github/workflows/docs_build.yml

@@ -0,0 +1,54 @@
+name: Docs build
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Install Node (22.x)
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22.x"
+          cache: pnpm
+          cache-dependency-path: pnpm-lock.yaml
+
+      - name: Enable Corepack
+        run: corepack enable
+
+      - name: Install Dependencies
+        run: pnpm install --frozen-lockfile --network-concurrency 1
+
+      - name: Cache Astro build
+        uses: actions/cache@v4
+        with:
+          path: .astro
+          key: astro-${{ hashFiles('astro.config.mjs', 'pnpm-lock.yaml') }}
+
+      - name: Build reference docs
+        run: pnpm docs:reference
+
+      - name: Build llms.txt bundles
+        run: pnpm docs:llms
+
+      - name: Verify generated docs are up to date
+        run: git diff --exit-code -- docs/
+
+      - name: Generate robots.txt from config
+        run: pnpm docs:robots
+
+      - name: Generate .htaccess from config (Apache hosts only)
+        run: pnpm docs:htaccess
+
+      - name: Build Starlight site
+        run: pnpm docs:site

.gitignore

@@ -5,6 +5,23 @@
 /dist/
 /coverage/
 /jsdoc/
+/.astro/
+
+# Astro build-time mirrors of docs/llms*.txt — generated by
+# scripts/build-llms.ts so the bundles resolve at the deployed site
+# root. Canonical committed copies live at docs/llms.txt and
+# docs/llms-full.txt.
+/public/llms.txt
+/public/llms-full.txt
+
+# Generated by scripts/build-robots.ts from config/site.ts. Run
+# `pnpm docs:robots` (or `pnpm docs`) to (re)build.
+/public/robots.txt
+
+# Generated by scripts/build-htaccess.ts from config/site.ts. Apache-only
+# config; inert on hosts that don't honor .htaccess. Run
+# `pnpm docs:htaccess` (or `pnpm docs`) to (re)build.
+/public/.htaccess
 js-stellar-base/
 
 test/unit/out/

CONTRIBUTING.md

@@ -1,23 +1,177 @@
-# How to contribute
+# Contributing
+
+## How to contribute
 
 Please read the [Contribution Guide](https://github.com/stellar/docs/blob/master/CONTRIBUTING.md).
 
+## Releasing
+
+Releases publish to npm via the [`npm publish`](.github/workflows/npm_publish.yml)
+GitHub Actions workflow, which fires on `release.published`. The
+workflow runs `pnpm run preversion` (clean, format, build, test) and
+publishes with OIDC trusted publishing — no manual npm token needed.
+
+To cut a release:
+
+1. **Update [CHANGELOG.md](CHANGELOG.md):** move entries under
+   `## Unreleased` into a new versioned section. Heading format:
+   `## [vX.Y.Z](https://github.com/stellar/js-stellar-sdk/compare/v<previous>...v<new>)`.
+2. **Bump `"version"` in [package.json](package.json)** per
+   [semver](https://semver.org/): patch for fixes, minor for additions,
+   major for breaking changes.
+3. **Run `pnpm install`** so [pnpm-lock.yaml](pnpm-lock.yaml) picks up
+   the new version.
+4. **Open a release PR** with the changelog and version bump.
+5. **After it merges,** draft a GitHub release at
+   <https://github.com/stellar/js-stellar-sdk/releases/new> with tag
+   `vX.Y.Z` targeting `master`. Paste the new changelog section into
+   the release notes. Publishing the release triggers
+   [`npm_publish.yml`](.github/workflows/npm_publish.yml).
+
+If the publish workflow fails, fix the issue and re-run via
+`workflow_dispatch` from the Actions tab — no need to cut a new tag.
+
+## Documentation
+
+The docs system has three parts:
+
+1. **TSDoc comments in `src/`** — the source of truth for API
+   reference. Edited inline alongside code.
+2. **Markdown guides in `docs/guides/`** — task-oriented prose,
+   hand-written.
+3. **Generated reference and LLM bundles** — produced by build
+   scripts; never edited by hand.
+
+Authored and generated content are strictly separated: every file
+is either fully authored or fully generated. They never mix.
 
-# Releasing
-Just like with the [js-stellar-base](https://github.com/stellar/js-stellar-base) library, there are a few important things to remember when releasing a new version of the library.
+### Renderer portability
 
-In fact, you should follow [the steps there](https://github.com/stellar/js-stellar-base/blob/master/CONTRIBUTING.md#Releasing), first, except for this repository. Then, **if base has been updated**, you want to follow the additional steps here:
+The generated markdown under `docs/` targets no specific docs platform.
+Starlight is the current renderer (chosen for its content collection,
+sidebar autogeneration, and search), but the same `docs/` files should
+render under Mintlify, Docusaurus, GitBook, Hugo, Jekyll, or any
+plain-markdown viewer (including raw GitHub view) without modification.
+That portability is a hard rule — when authoring TSDoc comments, guide
+markdown, or extending the build pipeline, do not introduce
+platform-specific syntax in the generated output:
 
- - [ ] First, bump its version accordingly. This is straightforward: change the version field of `"stellar-base"` under the `"dependencies"` section in the SDK's [package.json](https://github.com/stellar/js-stellar-sdk/blob/master/package.json#L140), e.g.:
+- No MDX components (`<Tabs>`, `<Card>`, `<TabItem>`, etc.).
+- No Starlight-specific directives or admonitions (`:::note`, `:::tip`,
+  `:::caution`).
+- Frontmatter limited to the universal `title` / `description`
+  convention. Avoid platform-private fields.
+- Cross-references between pages emitted as relative markdown links
+  (`./other-bucket.md#anchor`), never absolute URLs that bake in any
+  one platform's routing.
 
-```diff
-  "dependencies": {
-     ...
--    "stellar-base": "^1.0.0",
-+    "stellar-base": "^2.0.0",
-  }
+Renderer-specific configuration belongs in `astro.config.mjs` and
+`src/content.config.ts`, not in the markdown.
+
+### Layout
+
+- `src/**/*.ts` — TSDoc comments here drive the API reference.
+- `docs/guides/*.md` — task-oriented guides (authored).
+- `docs/reference/*.md` — API reference (generated; do not edit).
+- `docs/llms.txt`, `docs/llms-full.txt` — LLM-targeted bundles
+  (generated; do not edit).
+- `docs/index.md`, `docs/agents.md` — landing pages (authored).
+
+### Frontmatter
+
+Every authored guide markdown file starts with Starlight
+frontmatter:
+
+```yaml
+---
+title: <page title>
+description: <one-line summary>
+---
 ```
 
-  - [ ] Finally, run `pnpm install` so that the dependency is pulled (ensuring it's a valid version) and the lockfile is updated with the latest integrity details. You can now commit the change and PR accordingly.
+Reference files under `docs/reference/` carry generator-emitted
+frontmatter. Don't add new TSDoc tags to influence frontmatter —
+the generator handles it.
+
+### Build commands
+
+| Command               | Purpose                                          |
+| --------------------- | ------------------------------------------------ |
+| `pnpm docs:reference` | Regenerate API reference markdown from TSDoc.    |
+| `pnpm docs:llms`      | Regenerate `llms.txt` and `llms-full.txt`.       |
+| `pnpm docs:site`      | Build the static Starlight site to `dist/site/`. |
+| `pnpm docs`           | Run all three in order.                          |
+
+### Local preview
+
+- `pnpm docs:dev` — Astro dev server with hot-module reload.
+  Use while authoring guides; changes appear live.
+- `pnpm docs:preview` — production-mode preview (run after
+  `pnpm docs:site`). Use for visual and responsive checks before
+  merging or releasing.
+
+### Adding a new exported symbol
+
+1. Add or update the TSDoc comment in `src/`.
+2. Tag the export with `@category` so it appears in the right
+   reference section.
+3. Run `pnpm docs:reference`.
+4. Commit the regenerated files in `docs/reference/` alongside
+   the source change.
+
+### Adding a new guide
+
+1. Create `docs/guides/<slug>.md` with the frontmatter shown
+   above.
+2. The sidebar picks up the new file automatically — no config
+   change needed.
+
+### Images
+
+- Astro's `<Image>` component for raster images. It emits
+  WebP/AVIF and a responsive `srcset` automatically.
+- Inline SVG for vector diagrams.
+- Avoid unbounded raw `<img>` tags.
+
+### `llms.txt` and `llms-full.txt`
+
+- `llms.txt` is the LLM sitemap: project H1, blockquote tagline,
+  version metadata, and per-area `## Guides` / `## Reference` /
+  `## Other` sections with link lists to every published doc page.
+- `llms-full.txt` concatenates the full content of every doc page
+  into one bundle for AI-agent ingestion.
+
+Both are produced by `pnpm docs:llms` from the contents of `docs/`.
+Never edit them by hand.
+
+### CI rule
+
+Pull requests fail if the generated reference docs or LLM bundles
+are stale. Before pushing:
+
+```sh
+pnpm docs:reference
+pnpm docs:llms
+git diff docs/   # should be empty
+```
+
+If `git diff docs/` shows changes, commit them.
+
+### Source-link ref
+
+Per-symbol "Source:" links in the generated reference and the
+`Source ref:` field in `llms.txt` are pinned to a configurable
+ref so local builds, PR-check builds, and release deploys can
+each produce the right URLs without churning each other:
+
+- **Default**: trunk branch (`master`). Set in
+  [scripts/docs-source-ref.ts](scripts/docs-source-ref.ts) — update
+  there if the trunk branch is renamed.
+- **Override** via the `DOCS_SOURCE_REF` env var. Release deploys
+  set it to the release tag (e.g. `v15.0.1`) so the deployed
+  snapshot links to the exact release source. Locally:
+  `DOCS_SOURCE_REF=v15.0.1 pnpm docs:reference`.
 
-Note that new versions will be published to npm **and** Bower by GitHub Actions.
+Because the default is evergreen, repeated `pnpm docs:reference`
+or `pnpm docs:llms` runs are byte-idempotent — no per-commit SHA
+churn in `docs/`.

README.md

@@ -1,12 +1,12 @@
 # Stellar JS SDK (js-stellar-sdk)
 
 
-<a href="https://badge.fury.io/js/@stellar%2Fstellar-sdk"><img src="https://badge.fury.io/js/@stellar%2Fstellar-sdk.svg" alt="npm version" height="18"></a>
-<a href="https://www.npmjs.com/package/@stellar/stellar-sdk">
-  <img alt="Weekly Downloads" src="https://img.shields.io/npm/dw/@stellar/stellar-sdk" />
-</a>
-<a href="https://github.com/stellar/js-stellar-sdk/actions/workflows/tests.yml"><img alt="Test Status" src="https://github.com/stellar/js-stellar-sdk/actions/workflows/tests.yml/badge.svg" /></a>
-[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/stellar/js-stellar-sdk)
+<p class="badges">
+  <a href="https://badge.fury.io/js/@stellar%2Fstellar-sdk"><img src="https://badge.fury.io/js/@stellar%2Fstellar-sdk.svg" alt="npm version" height="18"></a>
+  <a href="https://www.npmjs.com/package/@stellar/stellar-sdk"><img alt="Weekly Downloads" src="https://img.shields.io/npm/dw/@stellar/stellar-sdk" /></a>
+  <a href="https://github.com/stellar/js-stellar-sdk/actions/workflows/tests.yml"><img alt="Test Status" src="https://github.com/stellar/js-stellar-sdk/actions/workflows/tests.yml/badge.svg" /></a>
+  <a href="https://deepwiki.com/stellar/js-stellar-sdk"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki" /></a>
+</p>
 
 `js-stellar-sdk` is a JavaScript library for communicating with a
 [Stellar Horizon server](https://developers.stellar.org/docs/data/apis/horizon) and [Stellar RPC](https://developers.stellar.org/docs/data/apis/rpc).
@@ -98,7 +98,7 @@ The usage documentation for this library lives in a handful of places:
 
  * across the [Stellar Developer Docs](https://developers.stellar.org), which includes tutorials and examples,
  * within [this repository itself](https://github.com/stellar/js-stellar-sdk/blob/master/docs/reference/readme.md), and
- * on the generated [API doc site](https://stellar.github.io/js-stellar-sdk/).
+ * on the generated [API doc site](https://stellar.github.io/js-stellar-sdk/) — which also publishes [agent-friendly bundles, raw markdown siblings, and a crawler policy](https://stellar.github.io/js-stellar-sdk/agents/) for AI tools. The site's URL, base path, and AI policy values live in [`config/site.ts`](config/site.ts).
 
 You can also refer to: