@panaversity/ksor 0.0.31 → 0.0.32

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @panaversity/ksor
 
+## 0.0.32
+
+### Patch Changes
+
+- 658c496: One instruction per tool, as tabs.
+
+  A document that has to say the same thing two ways — one command for one agent,
+  another for another — can now put each in its own fenced block and give the
+  fence a `tab`:
+
+  ````markdown
+  ```bash tab="Claude Code" tab-group="agent"
+  curl -fsSL https://claude.ai/install.sh | bash
+  ```
+
+  ```bash tab="OpenCode" tab-group="agent"
+  curl -fsSL https://opencode.ai/install | bash
+  ```
+  ````
+
+  Consecutive blocks declaring a `tab` become one tab group. **This is still
+  CommonMark** — a fence's info string is free text, so any other markdown reader
+  shows both blocks one after another, correct and readable, just without the
+  picker. Nothing framework-shaped enters `knowledge/`.
+
+  `tab-group` is the part worth knowing: blocks sharing a group name switch
+  together across the whole page, and the choice is remembered for the reader's
+  next visit. A document with ten tabbed sections is one decision rather than ten.
+
+  A tool the site recognises takes its own colour and mark on its tab — Claude
+  Code and OpenCode ship known. Anything else renders in the site's own accent,
+  which is the right default for tabs that are `npm`/`pnpm` or `US`/`EU`. The list
+  lives in `system/site/app/global.css` and is yours to extend or delete.
+
 ## 0.0.31
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panaversity/ksor",
-  "version": "0.0.31",
+  "version": "0.0.32",
   "description": "Knowledge System of Record — compile governed markdown into a static site for people and an MCP server for AI agents, with citations and measured abstention.",
   "keywords": [
     "abstention",

package/templates/scaffold/AGENTS.md

@@ -633,6 +633,35 @@ CI — and a first deploy without it serves an empty record. Full walkthrough:
   Declaring both `deck:` and `slides.url:` is refused — two presentations with
   nothing to say which one governs.
 
+- **One instruction per tool, as tabs.** When a document has to say the same
+  thing two ways — one command for one agent, another for another — put each in
+  its own fenced block and give the fence a `tab`:
+
+  ````markdown
+  ```bash tab="Claude Code" tab-group="agent"
+  curl -fsSL https://claude.ai/install.sh | bash
+  ```
+
+  ```bash tab="OpenCode" tab-group="agent"
+  curl -fsSL https://opencode.ai/install | bash
+  ```
+  ````
+
+  Consecutive blocks that declare a `tab` become one tab group. This is still
+  CommonMark: a fence's info string is free text, so any other markdown reader
+  shows both blocks one after another — correct, just without the picker.
+
+  **`tab-group` is what makes the choice stick.** Blocks sharing a group name
+  switch together across the whole page and the choice is remembered for the
+  reader's next visit, so a document with ten tabbed sections is one decision
+  rather than ten. Leave it off and each group is independent, which is almost
+  never what you want. Use the same group name for the same axis throughout a
+  record.
+
+  A tool the site knows gets its own colour and mark on its tab; anything else
+  renders in the site's accent. The list lives in `system/site/app/global.css`
+  and is yours — adding a tool is one colour and one mark.
+
 - Copy load-bearing values (numbers, thresholds, dates) exactly from their
   source, and name the source in `provenance`.
 

package/templates/scaffold/system/site/app/global.css

@@ -274,6 +274,97 @@ html > body[data-scroll-locked] {
   --ksor-caution: #e0906e;
 }
 
+/* A tool's own colour, across the whole block.
+
+   When a document gives one instruction per tool, the tab is the moment a
+   reader picks theirs, so the choice is worth being unmistakable. The colour
+   is not confined to the tab: the strip and the panel take a wash of it too,
+   in two different strengths, so the block says which tool you are reading at
+   any scroll position and the strip still reads as a distinct band.
+
+   Each tool declares ONE value and shared rules do the rest, so adding a tool
+   is a line rather than a set. `:has()` lifts the active tab's colour onto the
+   container, which is what lets the panel follow the tab.
+
+   Keyed on `data-tab-value`, which `components/mdx.tsx` puts on the trigger.
+   Radix also encodes the value in its generated id, but that is a private
+   format and keying on it would drop the branding silently if it changed.
+
+   THIS BLOCK IS YOURS. These are the tools this scaffold happened to know
+   about; a tab value matching nothing renders in the site's own accent, which
+   is the right default for a record whose tabs are npm/pnpm or US/EU. Add
+   your own, or delete the block — nothing else depends on it. Values are the
+   vendors' own. */
+.prose [data-orientation]:has([data-tab-value="Claude Code"][data-state="active"]) {
+  --ksor-tool: #da7756;
+}
+
+.prose [data-orientation]:has([data-tab-value="OpenCode"][data-state="active"]) {
+  --ksor-tool: #6366f1;
+}
+
+/* A decorative mark per tool. Purely visual — the label beside it is the
+   accessible name — so it is CSS content rather than markup an author would
+   have to write. */
+.prose [role="tab"][data-tab-value="Claude Code"]::before {
+  content: "\2726";
+}
+
+.prose [role="tab"][data-tab-value="OpenCode"]::before {
+  content: "</>";
+  font-size: 0.85em;
+  letter-spacing: -0.05em;
+}
+
+/* Everything below is shared, and applies only where a tool was recognised. */
+.prose [data-orientation]:has([data-tab-value][data-state="active"]) {
+  background-color: color-mix(in oklab, var(--ksor-tool) 7%, transparent);
+  border-color: color-mix(in oklab, var(--ksor-tool) 28%, transparent);
+  overflow: hidden;
+}
+
+/* The strip is a BAND: stronger than the panel, full width, and the tabs sit
+   inside it rather than floating above it. */
+.prose [data-orientation]:has([data-tab-value][data-state="active"]) > [role="tablist"] {
+  background-color: color-mix(in oklab, var(--ksor-tool) 20%, transparent);
+  border-bottom: 1px solid color-mix(in oklab, var(--ksor-tool) 26%, transparent);
+  padding: 0.5rem;
+  gap: 0.25rem;
+}
+
+.prose [role="tab"][data-tab-value] {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+  /* Big enough to be a target and to read as a block rather than a word. */
+  padding: 0.7rem 1.5rem;
+  font-size: 0.95rem;
+  font-weight: 600;
+  border-radius: 0.25rem;
+}
+
+.prose [role="tab"][data-tab-value][data-state="active"] {
+  background-color: var(--ksor-tool);
+  color: #fff;
+}
+
+.prose [role="tab"][data-tab-value][data-state="inactive"]:hover {
+  background-color: color-mix(in oklab, var(--ksor-tool) 14%, transparent);
+}
+
+/* The code sits INSET on the wash, with its own surface, so the panel reads as
+   a frame around it. A tinted block on a tinted panel is one colour with words
+   in it, and the code is the part somebody actually has to read. */
+.prose [data-orientation]:has([data-tab-value][data-state="active"]) figure {
+  margin: 1.25rem;
+  background-color: var(--card);
+  border-color: color-mix(in oklab, var(--ksor-tool) 18%, transparent);
+}
+
+.dark .prose [data-orientation]:has([data-tab-value][data-state="active"]) figure {
+  background-color: color-mix(in oklab, var(--muted) 88%, #000);
+}
+
 /* The slide STAGE.
 
    A slide is a projected surface, and reading as one at a glance is most of

package/templates/scaffold/system/site/components/mdx.tsx

@@ -1,9 +1,37 @@
 import defaultMdxComponents from "fumadocs-ui/mdx";
+import { CodeBlockTabsTrigger } from "fumadocs-ui/components/codeblock";
+import { Tab, Tabs } from "fumadocs-ui/components/tabs";
 import type { MDXComponents } from "mdx/types";
+import type * as React from "react";
+
+/**
+ * A tab trigger that says WHICH tab it is, in an attribute we own.
+ *
+ * Radix already encodes the value in its generated `id`
+ * (`radix-…-trigger-Claude Code`), and styling could key on that — but that is
+ * a private format, so a change upstream would drop the branding silently and
+ * nothing would go red. One attribute of our own costs a few lines and cannot
+ * be taken away.
+ *
+ * `app/global.css` uses it to give a known tool its own colour; a tab value it
+ * does not recognise simply renders in the site's own accent.
+ */
+function BrandedTabsTrigger({
+  value,
+  ...props
+}: React.ComponentProps<typeof CodeBlockTabsTrigger>): React.ReactElement {
+  return <CodeBlockTabsTrigger data-tab-value={value} value={value} {...props} />;
+}
 
 export function getMDXComponents(components?: MDXComponents) {
   return {
     ...defaultMdxComponents,
+    // `remarkCodeTab` (source.config.ts) rewrites consecutive fenced blocks
+    // that declare `tab="…"` into these, so they have to be in the map or the
+    // build fails on an unknown component rather than at authoring time.
+    Tabs,
+    Tab,
+    CodeBlockTabsTrigger: BrandedTabsTrigger,
     ...components,
   } satisfies MDXComponents;
 }

package/templates/scaffold/system/site/source.config.ts

@@ -1,4 +1,5 @@
 import { defineCollections, defineConfig, defineDocs } from "fumadocs-mdx/config";
+import { remarkCodeTab } from "fumadocs-core/mdx-plugins/remark-code-tab";
 import { metaSchema, pageSchema } from "fumadocs-core/source/schema";
 import { z } from "zod";
 import { DeckSchema } from "./lib/deck";
@@ -114,6 +115,28 @@ export const slides = defineCollections({
 
 export default defineConfig({
   mdxOptions: {
-    // MDX options
+    /**
+     * Alternative versions of the same instruction, as TABS.
+     *
+     * A record often has to say the same thing twice — one way for one tool,
+     * one for another — and stacking both is how a reader follows the wrong
+     * one. `remarkCodeTab` turns consecutive fenced blocks that declare a
+     * `tab="…"` into a tab group.
+     *
+     * The reason this works HERE, where a JSX `<Tabs>` cannot: a fence's info
+     * string is free text in CommonMark. `\`\`\`bash tab="Claude Code"` is a
+     * perfectly ordinary bash block to every other markdown reader, which sees
+     * both blocks one after another and is not misled — it just does not get
+     * to pick. So the record stays framework-free (critical rule 2) and the
+     * site still renders the affordance.
+     *
+     * `CodeBlockTabs` rather than `Tabs`, and the difference is not cosmetic:
+     * only that branch honours `tab-group`, which is what makes ONE choice
+     * apply to every group on the page and persist to the next visit. The
+     * `Tabs` branch drops the attribute silently, so a reader with a
+     * ten-section document would pick their tool ten times (verified against
+     * fumadocs-core 16.14.5, remark-code-tab.js).
+     */
+    remarkPlugins: [[remarkCodeTab, { Tabs: "CodeBlockTabs" }]],
   },
 });