@dastyaresocial/ds-cs 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,135 @@
-# Temporary Holding Version
+# ds-cs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The CLI for [Dastyare Social — CS](https://cs.dastyare.social). Installs agent skills, wires up MCP, and authenticates to a channel.
+
+```bash
+npx ds-cs init
+npx ds-cs add post-with-media
+```
+
+## Why
+
+DS-CS already speaks two agent protocols — a REST API and an MCP server — but neither tells an agent *how* to use them. The constraints that matter (upload before you post; `kind=` filters stories while `type=` counts them; the oRPC URL must be absolute) are scattered across a README an agent will not read.
+
+Skills are that knowledge, in the form agents actually load. This CLI installs them.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `ds-cs init` | Create skills directories, optionally write MCP config |
+| `ds-cs add <skill\|source>` | Install skills from DS-CS or anywhere else |
+| `ds-cs list` | Show what is installed and where it came from |
+| `ds-cs update [skill…]` | Re-fetch skills that changed upstream |
+| `ds-cs remove <skill…>` | Uninstall from every agent |
+| `ds-cs search [query]` | Search installed skills |
+| `ds-cs mcp [agent]` | Print, or write, MCP server config |
+| `ds-cs login` | Store a channel URL and API key |
+| `ds-cs whoami` | Show the stored channel |
+| `ds-cs logout` | Remove stored credentials |
+
+## Sources
+
+```bash
+ds-cs add brand-config              # from the DS-CS registry (the default)
+ds-cs add owner/repo                # any GitHub skills repo
+ds-cs add owner/repo@skill          # one skill from that repo
+ds-cs add owner/repo@a,b            # several
+ds-cs add https://github.com/o/r/tree/main/skills/x
+ds-cs add ./my-skills               # a local directory
+ds-cs add https://…/SKILL.md        # a direct URL
+ds-cs add https://…/archive.tar.gz  # a zip or tarball of skills
+ds-cs add git@github.com:o/r.git    # any other git host
+ds-cs add owner/repo --list         # browse without installing
+```
+
+A bare word is a skill name from the DS-CS registry, because knowing where a skill lives should not be the user's problem. Anything source-shaped — `owner/repo`, a URL, a path — is treated as a source.
+
+GitHub repositories are fetched as tarballs rather than cloned: one HTTP request, no `git` binary required, and no repository hooks executed. Only non-GitHub git hosts fall back to `git clone`.
+
+## Where skills land
+
+The canonical copy always goes to `.agents/skills/<name>` — the directory OpenCode, Cursor, Codex and a dozen others already read. Every other target is symlinked to it, so an update lands everywhere at once and there is one source of truth per project.
+
+```bash
+ds-cs add brand-config -a claude-code        # also link into .claude/skills
+ds-cs add brand-config -a ./my-agent/skills  # or any directory you name
+ds-cs add brand-config --copy                # copy instead of symlink
+```
+
+Symlinks are the default because agents that disagree about skill content is a worse problem than agents that disagree about inode counts. `--copy` is there for filesystems where symlinks do not work; the CLI falls back to copying automatically if a symlink fails.
+
+Run `ds-cs init --list-agents` for the full table.
+
+## Lockfile
+
+Installs are recorded in `skills-lock.json`, in the same v1 format `npx skills` (vercel-labs) reads and writes. The two tools interoperate in one project without clobbering each other:
+
+```bash
+ds-cs add brand-config        # DS-CS skills
+npx skills add emilkowalski/skill   # third-party skills
+ds-cs list                   # reports both
+```
+
+Each entry records the source, the skill's path within it, and a content hash. `ds-cs update` compares against that hash and **refuses to overwrite a skill you have edited locally** — an agent's tweak to a skill is usually deliberate. `--force` overrides.
+
+## MCP
+
+```bash
+ds-cs login --url https://cs.example.com --api-key "$API_KEY"
+ds-cs mcp                    # print every client format
+ds-cs mcp claude-code        # write .mcp.json
+ds-cs mcp opencode           # write opencode.json
+```
+
+An existing config file is never overwritten. The snippet is printed for you to merge — clobbering a working MCP config to add one server is a bad trade.
+
+Remote (HTTP) works everywhere and is what most people want. Local (stdio, `bun run mcp`) is faster and works offline but needs a clone with `DATABASE_URL` set.
+
+## Credentials
+
+`ds-cs login` verifies the channel before saving, so a mistyped key surfaces at login rather than mid-task inside an agent. Credentials land in `~/.config/ds-cs/auth.json` at mode `0600` — outside the project, because a key that can delete content is one `git add -A` away from being published.
+
+```bash
+ds-cs whoami     # shows a redacted key
+ds-cs logout
+```
+
+`DS_CS_URL` and `DS_CS_API_KEY` override the stored values. `DS_CS_CONFIG_DIR` relocates the file.
+
+## Where the registry comes from
+
+`ds-cs add` resolves the DS-CS registry in this order:
+
+1. **A local checkout** — a DS-CS repo found by walking up from the current directory. Edit a skill and reinstall it and you get your edit, not whatever `main` says.
+2. **The copy bundled in this package** — `prepack` copies `skills/` into the published package. This is the normal path for an installed CLI, and it works with no network at all. It also guarantees the registry matches the CLI version you have.
+3. **GitHub** — a fallback for a CLI older than the skills it wants. Only the `skills/` subtree is fetched; the full repo tarball is ~28MB, almost all of it `public/` and generated assets, and reading it to get ten markdown files is not a trade worth making.
+
+The repo's `skills/` is the source of truth. The copy inside this package is a build artefact, regenerated on `prepack` and gitignored.
+
+## Publishing a skill to the registry
+
+DS-CS skills live in [`skills/`](../../skills) in this repository. A skill is a directory with a `SKILL.md` whose frontmatter carries a `name` and a `description`:
+
+```
+skills/
+  dev/add-orpc-endpoint/SKILL.md
+  product/post-with-media/SKILL.md
+```
+
+The description is the whole interface — it is what an agent reads to decide whether to load the skill. Write it as "use when X", and name the sibling skills it should *not* be used for. Reference files, scripts and templates sit next to `SKILL.md` in the same directory and travel with it.
+
+Set `metadata.internal: true` to hide a skill from discovery until `INSTALL_INTERNAL_SKILLS=1`.
+
+## Development
+
+```bash
+npm test          # node:test, no dependencies
+npm run dev -- --help
+```
+
+While working inside a DS-CS checkout, `ds-cs add` prefers the local `skills/` directory over the published registry, so edits reinstall immediately. Pass a source path explicitly to bypass that.
+
+## Requirements
+
+Node 18.17+. Zero runtime dependencies.

package/bin/ds-cs.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { main } from "../src/index.mjs";
+
+main(process.argv.slice(2)).catch((error) => {
+  // Anything reaching here is a bug in the CLI, not a user error. Report it in
+  // a shape a maintainer can act on, then exit non-zero so scripts can branch.
+  if (process.env.DS_CS_DEBUG) {
+    console.error(error);
+  } else {
+    console.error(`\nds-cs: ${error?.message ?? error}`);
+    if (error?.hint) console.error(`hint: ${error.hint}`);
+  }
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@dastyaresocial/ds-cs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "CLI for Dastyare Social — CS. Install DS-CS skills and third-party agent skills, wire up MCP, and authenticate to a channel.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "ds-cs": "bin/ds-cs.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skills",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "dev": "node ./bin/ds-cs.mjs",
+    "sync-skills": "node ./scripts/sync-skills.mjs",
+    "prepack": "node ./scripts/sync-skills.mjs"
+  },
+  "keywords": [
+    "ds-cs",
+    "dastyare-social",
+    "agent-skills",
+    "skills",
+    "mcp",
+    "cli",
+    "ai"
+  ],
+  "dependencies": {}
+}

package/skills/README.md

@@ -0,0 +1,71 @@
+# DS-CS agent skills
+
+First-party skills for [Dastyare Social — CS](https://cs.dastyare.social). Install them with:
+
+```bash
+npx ds-cs init
+npx ds-cs add                  # browse everything
+npx ds-cs add post-with-media  # or install one by name
+```
+
+## What is here
+
+### Working on the codebase — `dev/`
+
+For agents and humans changing DS-CS itself.
+
+| Skill | Covers |
+|---|---|
+| [`dev/add-orpc-endpoint`](dev/add-orpc-endpoint) | Adding a procedure to the internal oRPC router |
+| [`dev/add-component`](dev/add-component) | Components without breaking the design system |
+| [`dev/db-migration`](dev/db-migration) | Drizzle schema changes and migrations |
+| [`dev/release`](dev/release) | Version bump, annotated tag, push |
+
+### Operating a channel — `product/`
+
+For agents acting *on* a live channel.
+
+| Skill | Covers |
+|---|---|
+| [`product/post-with-media`](product/post-with-media) | Posts, media upload, pinning |
+| [`product/manage-stories`](product/manage-stories) | Ephemeral stories |
+| [`product/webhooks`](product/webhooks) | Signed event delivery |
+| [`product/brand-config`](product/brand-config) | Channel identity and the `/about` page |
+| [`product/self-host-deploy`](product/self-host-deploy) | Install, update, back up |
+| [`product/mcp-connect`](product/mcp-connect) | Connecting an agent over MCP |
+
+## Writing one
+
+A skill is a directory containing `SKILL.md`:
+
+```markdown
+---
+name: my-skill
+description: What it does and, more importantly, when to reach for it.
+---
+
+# My Skill
+
+Instructions.
+```
+
+The `description` is the entire interface. It is the only thing an agent sees before deciding whether to load the skill, so it has to answer "is this my problem?" in one line. Write it as *use when…*, and name the neighbouring skills that should be used instead — an agent that loads the wrong skill is worse than one that loads none.
+
+Keep `SKILL.md` to instructions. Reference material, scripts and templates go in the same directory under their own names; they travel with the skill and are loaded only when the instructions point at them.
+
+Add `metadata.internal: true` to hide a skill from discovery until `INSTALL_INTERNAL_SKILLS=1`.
+
+## Testing a change
+
+While inside a DS-CS checkout, `ds-cs add` installs from this directory rather than from GitHub, so edits take effect immediately:
+
+```bash
+npx ds-cs add brand-config --force
+```
+
+Run it from a scratch directory to test what a user actually gets:
+
+```bash
+mkdir /tmp/t && cd /tmp/t && git init -q
+node /path/to/ds-cs/scripts/cli/bin/ds-cs.mjs add brand-config
+```

package/skills/dev/add-component/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: add-component
+description: Add or change a React component in DS-CS without breaking the design system — token architecture, the no-shadow and 60% corner-smoothing global rules, liquid-glass usage, cva variants, and the "use client" boundary. Use when adding a UI component, restyling one, or reviewing a component for design-rule violations. Read docs/design-system.md before deviating from these rules.
+---
+
+# Adding a component
+
+## Read the two global rules first
+
+These are enforced for the **whole codebase**, not per component. Violating them is the most common way a change gets rejected.
+
+**1. No shadows, anywhere.** No `box-shadow`, no `text-shadow`, no `drop-shadow` filter. Surfaces sit flush with the page and never lift off it. `src/styles/globals.css` declares an *unlayered* reset so a `shadow-*` utility cannot override it — which means a stray `shadow-lg` in a `className` compiles, type-checks, and renders nothing. Remove those classes for clarity even though they are inert; they misdescribe intent.
+
+The single exception is `.liquid-glass`, and only as an **inset** stroke. Inset shadows fade inward and cannot cast outside the element, so the no-depth rule still holds.
+
+**2. Rounded content surfaces use 60% corner smoothing.** `border-radius` controls corner *size* (`rounded-xl`); `corner-shape` controls corner *shape* (the squircle). `superellipse()` takes an **exponent, not a percentage**: `2` is a plain circular arc, `2.5` is the continuous iOS/Figma corner, and anything **below `2` cuts the corner inward** — the opposite of smoothing. The app uses `2.5` everywhere via `--corner-smoothing`. It is declared once against every element except `.rounded-full` (true circles stay circles — smoothing pushes them to a square, squaring off every avatar, pill and round button) and `.w-full` (full-bleed bars — install/update banners, the pinned bar — keep circular corners). Never restate `superellipse()` in a component; override `--corner-smoothing` and say why.
+
+## Tokens
+
+Two layers, and the split is the point:
+
+- Raw values live in `:root` in `src/styles/globals.css`.
+- `@theme inline` re-exports them under Tailwind's colour namespace so utilities resolve to the live value instead of a build-time copy.
+
+**Add to `:root`.** Add an `@theme inline` mapping only when a Tailwind utility should reach it.
+
+```css
+:root {
+  --button-background: color-mix(in srgb, var(--primary) 10%, transparent);
+}
+
+@theme inline {
+  --color-button-background: var(--button-background);
+}
+```
+
+Never hardcode a raw colour (`#fff`, `oklch(0.65 0.19 41)`) in a component. Severity and hierarchy come from blur, translucency, wash gradients, rim borders and contrast — never from elevation.
+
+## The shape of a component
+
+`src/components/button.tsx` is the reference implementation:
+
+```tsx
+import { Slot } from "@radix-ui/react-slot";
+import { cva, type VariantProps } from "class-variance-authority";
+import type * as React from "react";
+
+import { cn } from "@/lib/utils";
+
+const buttonVariants = cva(
+  "inline-flex items-center justify-center rounded-full liquid-glass transition-all disabled:pointer-events-none disabled:opacity-60 outline-none cursor-pointer select-none text-xl md:text-2xl px-5 py-2",
+  {
+    variants: {
+      variant: {
+        primary:
+          "[--liquid-glass-bg:var(--button-background)] [--liquid-glass-border-color:var(--button-border)] text-button-foreground hover:opacity-60",
+        secondary:
+          "[--liquid-glass-bg:color-mix(in_srgb,var(--button-background)_20%,transparent)] [--liquid-glass-border-width:2px] [--liquid-glass-border-color:color-mix(in_srgb,var(--button-border)_50%,transparent)] text-button-foreground hover:opacity-60",
+      },
+    },
+    defaultVariants: { variant: "primary" },
+  }
+);
+
+function Button({
+  className,
+  variant = "primary",
+  asChild = false,
+  ...props
+}: React.ComponentProps<"button"> &
+  VariantProps<typeof buttonVariants> & {
+    asChild?: boolean;
+  }) {
+  const Comp = asChild ? Slot : "button";
+
+  return (
+    <Comp
+      data-slot="button"
+      data-variant={variant}
+      className={cn(buttonVariants({ variant, className }))}
+      {...props}
+    />
+  );
+}
+
+export { Button, buttonVariants };
+```
+
+The conventions in it:
+
+- Variants live in `cva`, not in `className` strings scattered across call sites.
+- Glass is tinted by **overriding tokens** (`[--liquid-glass-bg:...]`), never by restating the effect.
+- `data-slot` and `data-variant` are set so tests and Storybook can target elements without relying on classes.
+- `cn()` from `@/lib/utils` is `twMerge(clsx(...))` — always use it for class composition.
+- `asChild` via Radix `Slot` lets a component render as its child (`<Button asChild><Link/></Button>`). Preserve it when the element is interactive or navigable.
+
+## The client boundary
+
+Components that fetch call the **action layer**, never oRPC directly:
+
+```tsx
+"use client";
+
+import { getPosts } from "@/lib/actions/posts";
+```
+
+Server-side callers — the OG image route, for instance — import `@/lib/api/*` directly and never touch the RPC client. A relative `/api/rpc` URL has no meaning on the server.
+
+## Liquid glass
+
+`.liquid-glass` is the reusable translucent material for buttons, cards, panels and any surface that should read as glass. It is made of exactly four things, in order: `backdrop-filter: blur() saturate()`, a vertical wash gradient, a translucent background, and a rim from border width + colour.
+
+```tsx
+<div className="liquid-glass rounded-2xl px-6 py-4">…</div>
+<div className="liquid-glass [--liquid-glass-bg:color-mix(in_srgb,var(--primary)_22%,transparent)]" />
+```
+
+The stroke and the border are separate and complementary. `--liquid-glass-border-color` sets edge weight to match the install/update banners; the inset stroke adds the luminous rim. Do not merge them.
+
+Glass is invisible on a flat white background. Review it over a busy backdrop using the `Design System/Liquid Glass` Storybook story, not an isolated white canvas.
+
+## Tests and stories
+
+Component tests live in `src/components/__tests__/<name>.test.tsx` and use `bun:test`, `@testing-library/react`, and a `happy-dom` window set up per test:
+
+```tsx
+import { describe, it, expect, beforeEach } from "bun:test";
+import { render } from "@testing-library/react";
+import { Button } from "../button";
+import React from "react";
+import "@testing-library/jest-dom/vitest";
+import { Window } from "happy-dom";
+
+beforeEach(() => {
+  const window = new Window();
+  globalThis.window = window as any;
+  globalThis.document = window.document as any;
+  globalThis.navigator = window.navigator as any;
+  document.body.innerHTML = "";
+});
+
+describe("Button Component", () => {
+  it("renders with primary variant by default", () => {
+    const { getByText } = render(<Button>Click me</Button>);
+    expect(getByText("Click me")).toHaveAttribute("data-variant", "primary");
+  });
+});
+```
+
+`test-setup.ts` mocks `next/font/local` globally so components can use local fonts under test.
+
+Stories go in `src/components/<name>.stories.tsx` under the `Design System/*` namespace.
+
+## Accessibility
+
+Radix primitives are already a dependency — use them instead of hand-rolling behaviour. Anything that opens a surface is a dialog or a context menu, not a `div` with `onClick`. Every interactive element needs a visible focus state and an accessible name.
+
+## Verify
+
+```bash
+bun run test
+bun run lint
+bun run storybook   # then look at your component against the design-system stories
+```
+
+For animations, read the `animate` skill — duration, curve and interruptibility are decisions, not defaults.

package/skills/dev/add-orpc-endpoint/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: add-orpc-endpoint
+description: Add an internal oRPC procedure to the DS-CS router — the typed channel between the React client and the server. Use when adding a posts/stories procedure, exposing new server logic to the UI, or when an oRPC call 404s at runtime. For external/public endpoints use the REST layer under src/app/api instead — this skill is internal-only.
+---
+
+# Adding an oRPC procedure
+
+## What this layer is
+
+oRPC is the **internal, typed RPC channel between the React client and the server** for posts and stories. It is not a public API — external integrations and AI agents use REST under `src/app/api`. Do not add external-facing endpoints here.
+
+The transport path, end to end:
+
+```
+"use client" component
+      │  import { getPosts } from "@/lib/actions/posts"
+      ▼
+src/lib/actions/posts.ts          thin 1:1 wrapper, owns analytics calls
+      │  orpc.posts.list(input)
+      ▼
+RPCLink → POST /api/rpc/posts/list
+      ▼
+src/app/api/rpc/[...path]/route.ts   RPCHandler
+      ▼
+src/lib/orpc/router.ts               validates input, calls business logic
+      ▼
+src/lib/api/posts/*.ts               the actual work
+```
+
+## The five rules
+
+1. **Business logic goes in `src/lib/api/*`.** Never inline a database query in the router. The router validates and delegates.
+2. **Components import from `@/lib/actions/*`, never `@/lib/orpc/client`.** Transport concerns in a component make the client impossible to swap later.
+3. **One procedure, one action wrapper, 1:1.** No action wraps two procedures; no procedure has two actions.
+4. **Declare an input schema only if the procedure takes arguments.** `os.handler(...)` with no `.input()` for zero-arg procedures.
+5. **Add a test** to `src/lib/orpc/router.test.ts`.
+
+## Step 1 — the business logic
+
+Add to the matching module, `src/lib/api/posts/index.ts` or `src/lib/api/stories/index.ts`:
+
+```ts
+export async function getPostStats(id: string) {
+  const rows = await db.select().from(posts).where(eq(posts.id, id));
+  if (rows.length === 0) {
+    throw new Error("Post not found");
+  }
+  return { views: rows[0].views, media: rows[0].media };
+}
+```
+
+Throw a plain `Error` for the not-found case. Procedures throw plain `Error` throughout this codebase; oRPC masks the message as `INTERNAL_SERVER_ERROR` for the client, and no UI reads the text. If you need a machine-readable code, declare errors with `os.errors({ ... })` instead of relying on message text.
+
+## Step 2 — the procedure
+
+Add to `postsRouter` or `storiesRouter` in `src/lib/orpc/router.ts`. Import the business function at the top of the file alongside its siblings.
+
+With input:
+
+```ts
+  getStats: os.input(postIdInput).handler(async ({ input }) => {
+    return getPostStats(input.id);
+  }),
+```
+
+Reuse an existing input schema when one fits — `postIdInput` is `z.object({ id: z.string().min(1) })`. Define a new one near the others only when the shape is genuinely different:
+
+```ts
+const postStatsInput = z.object({
+  id: z.string().min(1),
+  includeDrafts: z.boolean().optional(),
+});
+```
+
+Without input:
+
+```ts
+  count: os.handler(async () => ({ total: await countPosts() })),
+```
+
+Input schemas are plain Zod v4 objects passed straight to `os.input()`. Zod 4 implements Standard Schema v1 natively, so there is no adapter package to import.
+
+**Output schemas are intentionally not declared.** Adding one is a behaviour change — oRPC will validate and strip on output. Do not add one as a drive-by.
+
+## Step 3 — the action wrapper
+
+Add to `src/lib/actions/posts.ts` (or `stories.ts`). Thin, 1:1, with the same defaulting the sibling wrappers do:
+
+```ts
+export async function getPostStats(id: string) {
+  const result = await orpc.posts.getStats({ id });
+  void captureClientEvent("post_stats_viewed", { post_id: id });
+  return result;
+}
+```
+
+Preserve the `captureClientEvent` call where sibling procedures in that file have one. Analytics calls live in the action layer, not the router — that is the whole reason the layer exists.
+
+## Step 4 — the test
+
+`src/lib/orpc/router.test.ts` mounts the real router behind a real `RPCHandler` and drives it through a real `RPCLink`, mocking only the business-logic layer. Add a case alongside the existing ones:
+
+```ts
+it("returns stats for a post", async () => {
+  const client = makeTestClient();
+  const result = await client.posts.getStats({ id: "post-1" });
+  expect(result.views).toBe("42");
+});
+
+it("rejects an empty post id", async () => {
+  const client = makeTestClient();
+  await expect(client.posts.getStats({ id: "" })).rejects.toThrow();
+});
+```
+
+Run `bun test` (never `bun test --isolate` alone — AGENTS.md requires the isolate flag via `bun run test`).
+
+## Two things that will bite you
+
+### The RPC URL must be absolute
+
+oRPC's `StandardRPCLink` does `new URL(baseUrl)`, which throws on a relative path. `resolveRpcUrl()` in `src/lib/orpc/client.ts` converts `/api/rpc` to an absolute URL using `window.location.origin`. It is a **function**, not a string constant, because `RPCLink.url` only invokes it when a request is actually issued — which is what makes touching `window` safe during SSR. Do not "simplify" it to a constant; the failure appears only at runtime, while type-checking passes.
+
+### The catch-all route segment is required
+
+The client addresses procedures as `/api/rpc/posts/list`. A route at `src/app/api/rpc/route.ts` matches only the bare `/api/rpc`, so every real call 404s into the not-found page. The `[...path]` segment is what makes `/api/rpc/...` resolve.
+
+## Dates survive on their own
+
+oRPC's Standard RPC serializer handles `Date`, `BigInt`, `Map`, `Set`, `URL`, `RegExp`, `NaN` and `undefined` natively via type tags in the response `meta` array. `superjson` was removed and is not needed. `PostWithReactions.createdAt` arrives at the client as a real `Date` — do not re-parse it, and do not add a serialization library.
+
+## Service Worker coupling
+
+`public/sw.js` intercepts `/api/rpc/` for the offline feed. `extractPostsFromResponse()` parses the `{ json, meta }` envelope and stores `createdAt`/`updatedAt` as ISO strings. If you add a procedure whose response the feed depends on, check whether the extractor needs to know about it.
+
+## Verify
+
+```bash
+bun run test        # full suite, isolated
+bun run lint
+```
+
+Then, if the procedure is reachable from a screen, run the app and click through the actual flow. A procedure that type-checks and passes its unit test can still 404 at runtime for the two reasons above.

package/skills/dev/db-migration/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: db-migration
+description: Add or change a Postgres table, column or index in DS-CS with Drizzle, including the generated migration, the drizzle-zod schemas, and applying it. Use when adding a table, adding a column to posts/stories, changing an index, or when "column does not exist" appears at runtime. Not for reading data — that is the oRPC/REST layer.
+---
+
+# Database migrations
+
+## The layout
+
+| Path | Role |
+|---|---|
+| `src/lib/db/schema/*.ts` | Table definitions — one file per table |
+| `src/lib/db/schema/index.ts` | Barrel export |
+| `src/lib/db/migrations/` | Generated SQL, committed |
+| `src/lib/db/migrate.ts` | Runtime migrator, used by the container on boot |
+| `drizzle.config.ts` | Points drizzle-kit at `schema` and `migrations` |
+
+Tables use `pgTable` with a `text` primary key (UUIDs are generated in application code, not by a database default), `jsonb` for structured columns, and a drizzle-zod schema exported alongside each one.
+
+## Commands
+
+```bash
+bun run db:generate   # drizzle-kit generate → writes SQL into src/lib/db/migrations
+bun run db:migrate    # apply pending migrations
+bun run db:push       # push schema directly + seed (development shortcut)
+bun run db:check      # verify migration history is consistent
+bun run db:studio     # browse the database
+```
+
+`db:push` is a development shortcut that skips the migration files. **Never** use it as the way to ship a schema change — the container runs `db:migrate` on boot, so a change that exists only in the live database is a change that vanishes on the next deploy.
+
+## Adding a table
+
+1. Create `src/lib/db/schema/<name>.ts`:
+
+```ts
+import { index, jsonb, pgTable, text, timestamp } from "drizzle-orm/pg-core";
+import { createInsertSchema, createSelectSchema } from "drizzle-zod";
+
+import { toZodV4SchemaTyped } from "@/lib/zod-utils";
+
+export const bookmarks = pgTable(
+  "bookmarks",
+  {
+    id: text("id").unique().primaryKey(),
+    postId: text("post_id").notNull(),
+    note: text("note"),
+    tags: jsonb("tags"),
+    createdAt: timestamp("created_at").$defaultFn(() => new Date()),
+    updatedAt: timestamp("updated_at")
+      .$defaultFn(() => new Date())
+      .$onUpdate(() => new Date()),
+  },
+  (table) => {
+    return {
+      bookmarksPostIdIdx: index("bookmarks_post_id_idx").on(table.postId),
+    };
+  }
+);
+
+export const selectBookmarksSchema = toZodV4SchemaTyped(createSelectSchema(bookmarks));
+
+// Use pick() instead of omit() to avoid Zod v4 compatibility issues with createErrorSchema
+export const insertBookmarksSchema = toZodV4SchemaTyped(
+  createInsertSchema(bookmarks).pick({ postId: true, note: true, tags: true })
+);
+
+export const patchBookmarksSchema = insertBookmarksSchema.partial();
+```
+
+2. Export it from `src/lib/db/schema/index.ts`.
+3. `bun run db:generate`, then review the generated SQL before applying.
+4. `bun run db:migrate`.
+
+## Adding a column
+
+Edit the table in place, then `bun run db:generate`. drizzle-kit asks whether the change is safe; the answer matters:
+
+- **Adding a column with a default or nullable** — safe, generates `ADD COLUMN`.
+- **Adding a NOT NULL column without a default to a table that already has rows** — drizzle-kit will warn. Either add a default, or add it as nullable and backfill in a second migration. One migration that both adds and backfills leaves no window where the column is missing, but it also locks the table for the duration; on `posts` and `stories`, prefer two migrations.
+
+Indexes are declared in the table's third argument with an explicit name (`postsCreatedAtIdx` → `posts_created_at_idx`). Name them consistently.
+
+## Conventions that are already decided
+
+- `id` is `text`, unique, primary key — generated in application code.
+- Timestamps use `$defaultFn(() => new Date())` and `$onUpdate(() => new Date())`.
+- `views` and `likes` are stored as `text` with a numeric string default, not `integer`. This is deliberate: they are display counters, and keeping them out of the numeric range avoids contention on hot rows. Read them with `Number(...)` and write them back as strings.
+- Enum-ish columns are `text({ enum: [...] })`, not a Postgres enum type.
+- Structured data is `jsonb`. It is not validated at the database level — the drizzle-zod schemas and the oRPC input schemas are where validation happens.
+
+## Verify
+
+```bash
+bun run db:check
+bun run db:migrate
+bun run test
+```
+
+Confirm the migration folder contains the new SQL and that it is committed. A migration that exists only on your machine reproduces fine locally and fails for everyone else.
+
+## Deploying
+
+The container runs `bun run db:migrate` before serving. For Vercel Fluid, the build script runs `db:migrate` as well. Either way the migration files are what ships — if they are not committed, deploys silently skip the change.