@nanisoft/prism-llms 0.4.0 → 0.5.0

package/README.md

@@ -0,0 +1,88 @@
+# @nanisoft/prism-llms
+
+Prism's agent-facing corpus. One build-fresh `dist/` is read three ways:
+
+| Lane | Consumer | What it reads |
+| --- | --- | --- |
+| npm | a downstream tool | the published `dist/` |
+| site | `@nanisoft/site` | a local build of `dist/` |
+| MCP | `@nanisoft/prism-mcp-server` | the bundled `dist/data.json`, at build time only |
+
+The generator is deterministic and `dist/` is never committed. The corpus is a
+projection, not a source: it is assembled from the checked catalogue, the
+hand-written MDX pages, the emitted `@nanisoft/prism-ui` declarations, the
+verbatim demo source and the emitted token cascade. Nothing here is hand-edited.
+
+## Commands
+
+```sh
+pnpm --filter @nanisoft/prism-llms build   # compile the library and emit the corpus
+pnpm --filter @nanisoft/prism-llms check   # the eight-invariant drift gate
+pnpm --filter @nanisoft/prism-llms test    # the Vitest floor
+```
+
+`build` writes the library with `tsc` and then the corpus with
+`scripts/build.mjs`. `emit(outDir)` is exported so the drift gate can emit twice
+into temporary directories and byte-compare. The gate never writes `dist/`.
+
+## Output
+
+The build writes exactly these paths into `dist/`:
+
+```text
+data.json
+llms.txt
+llms-full.txt
+prism-skill.md
+md/**
+demo-graph.d.ts
+demo-graph.js
+extractor.d.ts
+extractor.js
+index.d.ts
+index.js
+markdown.d.ts
+markdown.js
+store.d.ts
+store.js
+```
+
+`md/<section>/<slug>.md` is the per-item Markdown mirror for `section` in
+`overview`, `foundation`, `content`, `components`, `blocks`, `pages`,
+`changelogs`. A content page's mirror keeps the shape of the content tree it was
+read from, at any depth: a page at `content/foundation/tokens/spacing-scale.mdx`
+is emitted at `md/foundation/tokens/spacing-scale.md` and is linked as
+`/foundation/tokens/spacing-scale.md`. A page's route comes from where it sits
+in that tree, not from a Section-and-file-name join, so nesting a page publishes
+it rather than losing it. `data.json` is the `PrismDocsStore`; it is never copied
+into the site export and is bundled into the Worker instead.
+
+The content walk is `collectContentPages` in `scripts/build.mjs`, and it is the
+only thing that decides which content pages exist. A Section that is declared and
+not on disk throws rather than being skipped, because a skipped Section is a
+whole Section deleted from every agent surface with a green build.
+
+## The store
+
+`PrismDocsStore` is declared in `src/store.ts` and exported from the package
+root. `parsePrismDocsStore(raw: unknown)` is the one runtime guard; it narrows
+structurally, validates `kind` through a local list tied to the catalogue's
+closed union, and throws with the offending path. The MCP server inherits both
+the type and the guard.
+
+## The per-item spec
+
+Each mirror is generated to one fixed shape: the H1, the catalogue description,
+the import fence, the hand-written prose body, the demo, then a literal
+`## Props` heading followed by a one-entry-per-line definition list (or
+`## Composition` for a Block or a Page), with cross-references last. The
+definition-list format is load-bearing: the MCP server's regular expression keys
+on the literal `## Props` heading.
+
+## The drift gate
+
+`scripts/check.mjs` fails the build on any of eight invariants: coverage (every
+catalogue item, and every content page at any depth, has a mirror), the demo
+contract, cross-references, descriptions, the store type round-trip, link and
+mirror completeness, byte-for-byte determinism, and the README's declared output
+list equalling the emitted set.

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,48 @@
+# Third-party notices
+
+The Prism packages (`@nanisoft/prism-tokens`, `@nanisoft/prism-ui`,
+`@nanisoft/prism-llms`, `@nanisoft/prism-mcp-server`) are MIT-licensed. See
+[`LICENSE`](./LICENSE). This file covers the third-party works the packages and
+the site depend on or redistribute. It is attribution, not a grant: each work
+remains under its own license.
+
+## Runtime dependencies
+
+The direct runtime dependencies below are MIT-licensed unless noted. License
+texts ship with their packages and are available from the corresponding npm
+package or repository.
+
+| Package | Used by | License |
+| --- | --- | --- |
+| `@base-ui/react` | `@nanisoft/prism-ui` (internal accessibility behaviour) | MIT, copyright the MUI Team and contributors |
+| `@modelcontextprotocol/sdk` | `@nanisoft/prism-mcp-server` | MIT, copyright Anthropic, PBC and contributors |
+| `zod` | `@nanisoft/prism-mcp-server` | MIT, copyright Colin McDonnell |
+| `react`, `react-dom` | `@nanisoft/prism-ui` (peer), the site | MIT, copyright Meta Platforms, Inc. and affiliates |
+| `next` | the site | MIT, copyright Vercel, Inc. |
+| `fumadocs-core`, `fumadocs-mdx` | the site | MIT, copyright Fuma Nama |
+| `agents` | the site (MCP transport) | MIT, copyright Cloudflare, Inc. |
+| `class-variance-authority` | `@nanisoft/prism-ui` (internal variant recipes, not re-exported) | Apache-2.0 |
+| `clsx` | `@nanisoft/prism-ui` (internal class composition) | MIT, copyright Luke Edwards |
+| `tailwind-merge` | `@nanisoft/prism-ui` (internal class composition) | MIT |
+| `lucide-react` | `@nanisoft/prism-ui` and the site (icons) | ISC, copyright the Lucide contributors, with portions copyright Cole Bemis 2013 to 2023 as part of Feather (MIT) |
+| `tailwindcss` | `@nanisoft/prism-ui` and the site (internal build dependency) | MIT, copyright Tailwind Labs, Inc. |
+
+Tailwind 4 is not a consumer dependency. It runs only in Prism's build, and its
+compiled output is part of the component package's precompiled `styles.css`.
+
+## Fonts
+
+The documentation site self-hosts Inter under `apps/site/src/fonts/`, loaded
+through `next/font/local`. The shipped files are `InterVariable.woff2` and
+`InterVariable-Italic.woff2` from the official Inter release 4.1, and the site
+is the only consumer. Inter is licensed under the **SIL Open Font License,
+Version 1.1**; the license text is committed at
+`apps/site/src/fonts/LICENSE.txt`. Inter is copyright The Inter Project Authors
+(rsms.me/inter).
+
+## Build and development toolchain
+
+TypeScript, Vitest, Turbo, pnpm, changesets, oxlint, Style Dictionary, publint
+and Wrangler are development and build dependencies. They are not redistributed
+with Prism artifacts and carry their own package licenses. Style Dictionary is
+Apache-2.0; the rest ship their own license text with their packages.