@dastyaresocial/ds-cs 0.0.0-stage → 0.1.0

package/skills/dev/release/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: release
+description: Cut a DS-CS release — version bump in package.json, selective staging, commit, annotated tag, and push. Use whenever someone says "ship it", "release", "stage and push changes", "bump the version", or asks to publish a new version. Also covers what makes the in-app update banner fire.
+---
+
+# Cutting a release
+
+## The rule that overrides everything
+
+**"Stage and push changes" is a release, not a commit.** A bare commit is never the right response. A version bump is always included; never push without one.
+
+## The sequence, in order
+
+### 1. Review first
+
+```bash
+git status
+git diff
+git diff --cached
+```
+
+Decide what is actually being released and whether anything unrelated is in the working tree. You must be able to state this before touching the index.
+
+### 2. Stage selectively
+
+Stage only the files belonging to this change. If unrelated edits are present, leave them unstaged and **say so explicitly** — never sweep them in silently.
+
+```bash
+git add <specific paths>
+git status   # confirm what is actually staged
+```
+
+### 3. Bump the version
+
+Read the current version from `package.json` — it is the source of truth.
+
+```bash
+npm version patch   # or minor / major
+```
+
+`next.config.ts` bakes it into the build as `NEXT_PUBLIC_APP_VERSION`, which is what drives the in-app update banner. Bumping the number without rebuilding means users never see the update prompt; that is expected, not a bug — the banner appears when a *later* build ships.
+
+| Change | Bump | Example |
+|---|---|---|
+| Bug fix, refactor, internal/infra change with no user-visible effect | **patch** | `v0.3.3` → `v0.3.4` |
+| New feature, new endpoint, new capability | **minor** | `v0.3.4` → `v0.4.0` |
+| Breaking change — removed/renamed public API, config or env var changes, DB migrations that break existing data | **major** | `v0.4.0` → `v1.0.0` |
+
+Judge the bump **from the diff**, not from the commit message.
+
+- Never skip a number.
+- Do not bump for a bump alone. If the diff is empty or contains only whitespace, stop and ask.
+- If the change sits between two levels, choose the **lower** one and mention the alternative in your report.
+
+### 4. Commit and push
+
+```bash
+git commit -m "<type>(<scope>): <summary>"
+git push origin main
+```
+
+### 5. Tag the commit you just pushed
+
+```bash
+git tag -l                      # existing tags
+git tag -l v0.3.4               # must be empty before you create it
+git tag -a v0.3.4 -m "v0.3.4"
+git push origin main --follow-tags
+```
+
+Tags are annotated (`-a`) and named `vMAJOR.MINOR.PATCH`. The tag points at the commit that carries that version.
+
+**Never move or force-update a tag that has already been pushed.** If the tag already exists, stop and ask.
+
+### 6. Report
+
+State the new version, the tag, and anything you deliberately left out of the release. If you staged selectively, name what you left behind.
+
+## Deploy surfaces
+
+| Surface | Trigger |
+|---|---|
+| Docker (`dastyaresocial/ds-cs`) | Image published from `main` after the tag lands |
+| Vercel | `next build` runs `generate:config`, `generate:icons`, `upload:emojis`, `db:migrate`, `bootstrap:admin` |
+
+`bun run build` is not just a bundle — it runs migrations and bootstraps the admin user. A build that succeeds locally has already touched the database if `DATABASE_URL` was set. That is why migration files must be committed before a release, not after.
+
+## Also worth doing
+
+```bash
+# Keep the changelog in step with the version
+$EDITOR CHANGELOG.md
+```
+
+Commit the changelog entry with the release, not as a follow-up commit — a tag that points at a commit missing its changelog entry is a release nobody can reconstruct.
+
+## Verify before you report done
+
+```bash
+bun run test
+bun run lint
+git log --oneline -3
+git tag -l "v$(npm pkg get version | tr -d '"')"
+```
+
+The last command should print the tag you just created.

package/skills/product/brand-config/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: brand-config
+description: Configure a DS-CS channel's identity — username, name, description, the /about resume page, and the profile image. Use when rebranding a channel, editing config/app.config.yml or config/about.config.yml, toggling the about page, or when someone asks to change the site name or bio. Changes apply on save with no rebuild or restart.
+---
+
+# Branding a channel
+
+## The live-edit model
+
+Three files control the channel's identity:
+
+| File | Controls | Applied by |
+|---|---|---|
+| `config/app.config.yml` | Username, email, channel name, description, meta, header, profile | reload the page |
+| `config/about.config.yml` | The `/about` page — enabled flag, bio, contacts, work/education sections | refresh `/about` |
+| `public/profile-image.png` | The channel avatar | reload |
+
+All three are read from disk on **every request**. Save the file, reload the browser, and the change is live. **No rebuild. No `docker compose restart`.** Hard-refresh to bypass caching.
+
+`docker-compose.yml` bind-mounts the whole `./config` directory rather than individual files, so editors that save via atomic rename (VS Code, most others) cannot orphan the inode the container is watching.
+
+## app.config.yml
+
+```yaml
+general:
+  username: "omidshabab"
+  email: "hey@example.com"
+
+en:
+  name: "Your Name"
+  desc: "Short description used in meta tags and on the /about page."
+```
+
+`general.username` is the account handle. `general.email` is the contact shown in the footer and contact links. Each locale key (`en`, and any others you add) carries `name` and `desc`; `name` drives the browser tab, the header, and SEO, and `desc` drives meta tags and `/about`.
+
+This file is compiled to `config/app.config.json` at build time by `bun run generate:config`, and the JSON twin is what the client bundle imports. The runtime editor path re-reads the YAML on each request, which is what makes live edits work without a rebuild.
+
+## about.config.yml
+
+The first key **must** be `enabled:`, and `general.name` must be non-empty — the API enforces both.
+
+```yaml
+enabled: true
+general:
+  name: "Your Name"
+  jobTitle: "Builder"
+  website: "https://example.com"
+  about: "A longer bio."
+  contacts:
+    - label: "Email"
+      value: "you@example.com"
+content:
+  - title: "Work Experience"
+    items:
+      - title: "Role"
+        company: "Company"
+        period: "2024 — present"
+        description: "What you did."
+  - title: "Education"
+    items:
+      - title: "Degree"
+        school: "University"
+        period: "2020 — 2024"
+```
+
+When `enabled` is false, `/about` renders the not-found page and leaves the sitemap. **All other data is preserved** — toggling visibility is a one-key flip, not a rewrite.
+
+### Via the API or MCP
+
+```bash
+# read the current config
+curl https://cs.example.com/api/...   # or use the get_resume_config MCP tool
+
+# toggle visibility without touching content — preferred
+#   MCP tool: set_resume_enabled { "enabled": false }
+```
+
+`update_resume_config` replaces the **whole file** from a YAML string, so read the current config first and edit it — a blind overwrite silently discards every section. `set_resume_enabled` is the safe operation for visibility: it flips one key and preserves everything else.
+
+## Profile image
+
+Replace `public/profile-image.png` in place. It is served at `/profile-image.png` with `no-store`, your file wins over the baked default, and if the file is missing at startup the default is seeded in so the URL always resolves. `docker compose up` never copies over it.
+
+## Verify
+
+```bash
+docker compose logs -f app      # config parse errors surface here
+```
+
+Then reload the site and `/about`. If a change did not appear, the YAML is the thing to suspect first — an indentation error or a missing `general.name` makes the config fall back rather than crash, which reads as "my edit did nothing".
+
+## Mistakes that cost time
+
+- Restarting Docker after a config edit. Unnecessary, and it hides the real problem.
+- Putting `enabled:` anywhere but the first line of `about.config.yml` — the API rejects it.
+- Calling `update_resume_config` with a partial document and wiping the resume.
+- Editing `config/app.config.json` directly. It is generated; the YAML is the source of truth and your edit is overwritten on the next `generate:config`.
+- Replacing `profile-image.png` with a different filename. The route serves that exact path.

package/skills/product/manage-stories/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: manage-stories
+description: Create, list, view, like, update and delete ephemeral stories on a DS-CS channel over REST or MCP. Use for 24-hour content, vertical video or image stories, story counters, or cleaning up expired story ids. For feed posts use post-with-media; for realtime notifications use webhooks.
+---
+
+# Working with stories
+
+## How stories differ from posts
+
+Stories are **ephemeral** — short-lived, single-media, portrait-first. They have no `content` field, no pin, and no reactions; they have `views` and `likes` counters instead. Everything else — auth, media upload, the API-key rate limit — is identical to posts.
+
+```
+Auth:      Authorization: Bearer <API_KEY>     (writes only; reads are public)
+Media:     upload first, then reference the returned URL by media type
+```
+
+## Upload the media first
+
+Stories only accept `image` and `video`. Use the same upload endpoints as posts:
+
+```bash
+curl -X POST https://cs.example.com/api/upload \
+  -H "Authorization: Bearer $API_KEY" \
+  -F "file=@clip.mp4"
+```
+
+Video limit is 100 MB; image limit is 10 MB. Stories are portrait-first — 1080×1920 is the intended shape, and it is what the story viewer lays out for.
+
+## Create
+
+```bash
+curl -X POST https://cs.example.com/api/stories \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "type": "video",
+    "media": {
+      "url": "https://…/media/video/abc.mp4",
+      "width": 1080,
+      "height": 1920,
+      "duration": 18
+    }
+  }'
+```
+
+`type` is `image` or `video`. `media` accepts **either** a single object or an array — an array creates **one story per item** and returns the first, so if you post three clips you get three stories and must list to find the other two.
+
+You can also set counters at creation time, which is useful when backfilling or seeding:
+
+```json
+{ "type": "image", "media": { "url": "…" }, "views": 120, "likes": 9 }
+```
+
+## Read
+
+```bash
+GET /api/stories?page=1&limit=20
+GET /api/stories?type=count          # { "total": n }
+GET /api/stories?kind=image          # filter by media kind
+GET /api/stories?kind=video
+GET /api/stories?search=keyword
+GET /api/stories/{story_id}
+```
+
+Note the asymmetry: the **count** parameter is `type=count`, but the **media filter** is `kind=image` / `kind=video`. Using `type=image` for the filter does nothing.
+
+## Views and likes
+
+```bash
+# increment
+curl -X POST "https://cs.example.com/api/stories/$ID?action=view"
+
+# like
+curl -X POST "https://cs.example.com/api/stories/$ID?action=like&direction=inc"
+curl -X POST "https://cs.example.com/api/stories/$ID?action=like&direction=dec"
+```
+
+`action=view` is public — it is what the player fires. `direction` is `inc` or `dec`; there is no toggle, so a double-tap from a client that sends `inc` twice over-counts. If you are wiring a reaction UI, read the current `likes` first and send the direction that moves it the way you want.
+
+## Update
+
+```bash
+curl -X PATCH https://cs.example.com/api/stories/$ID \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"views": 500, "media": {"url": "https://…/new.mp4", "width":1080, "height":1920}}'
+```
+
+Partial update over `type`, `views`, `likes`, `media`.
+
+## Delete
+
+```bash
+curl -X DELETE https://cs.example.com/api/stories/$ID \
+  -H "Authorization: Bearer $API_KEY"
+```
+
+Permanent.
+
+## Via MCP
+
+| Tool | Auth | Purpose |
+|---|---|---|
+| `list_stories` | public | Paginated, searchable |
+| `get_story` | public | One story |
+| `count_stories` | public | Total |
+| `create_story` | API key | Create from a media URL |
+| `update_story` | API key | Media, views, likes |
+| `delete_story` | API key | Remove |
+
+`ds-cs mcp` prints ready-to-paste config for every major client.
+
+## Mistakes that cost time
+
+- Filtering with `type=image` instead of `kind=image` and getting the full list back.
+- Posting an array and assuming one story was created — you created one per item.
+- Sending `action=like` with no `direction`. It is `inc` or `dec`, never a toggle.
+- Attaching an image URL to a story without uploading it first.
+- Expecting a `content` caption field. Stories do not have one.

package/skills/product/mcp-connect/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: mcp-connect
+description: Connect an AI agent to a DS-CS channel over MCP — remote HTTP or local stdio — and choose the right transport for the situation. Use when setting up Claude Desktop, Cursor, Claude Code, OpenCode or Windsurf against a channel, when MCP tools are not appearing, or when an agent needs read or write access to a channel's posts and stories.
+---
+
+# Connecting an agent over MCP
+
+## Why this exists
+
+Without MCP, an agent has to read docs, guess URLs, and hand-build HTTP requests — it works, and it gets the auth header wrong. With MCP the agent asks the server what tools exist and gets typed schemas. For anything an agent does repeatedly against a channel, wire MCP rather than teaching it `curl`.
+
+## Two transports
+
+**Remote (HTTP)** — the channel serves MCP at `/api/mcp`. Any client connects over the network. No local process, works for clients on other machines, survives the channel moving.
+
+**Local (stdio)** — `bun run mcp` runs a stdio server that talks straight to the database. Faster and works offline, but requires a local clone with `DATABASE_URL` and `API_KEY` set. Useful in development; not what a user should be running.
+
+## Let the CLI write the config
+
+```bash
+ds-cs login --url https://cs.example.com --api-key "$API_KEY"
+ds-cs mcp                       # print every format
+ds-cs mcp claude-code           # write .mcp.json
+ds-cs mcp opencode              # write opencode.json
+ds-cs mcp cursor                # write .cursor/mcp.json
+```
+
+`ds-cs init --mcp` does the same during project setup. An existing config file is never overwritten — the CLI prints the snippet and leaves the merge to you, because clobbering a working MCP config to add one server is a bad trade.
+
+## The config
+
+**Remote with write access:**
+
+```json
+{
+  "mcpServers": {
+    "ds-cs": {
+      "url": "https://cs.example.com/api/mcp",
+      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
+    }
+  }
+}
+```
+
+**Local:**
+
+```json
+{
+  "mcpServers": {
+    "ds-cs": { "command": "bun", "args": ["run", "mcp"], "cwd": "/path/to/ds-cs" }
+  }
+}
+```
+
+Dropping the `headers` block leaves read-only access — which works, because reads are public by design.
+
+## Tools
+
+**Read (no auth):** `list_posts`, `get_post`, `list_stories`, `get_story`, `count_stories`, `get_resume_config`
+
+**Write (API key):** `create_post`, `update_post`, `delete_post`, `create_story`, `update_story`, `delete_story`, `update_resume_config`, `set_resume_enabled`
+
+## Auth
+
+Read tools work without a key. Write tools require `Authorization: Bearer <API_KEY>`, where the key is the channel's `API_KEY` from `.env`. The remote HTTP server always uses `API_KEY`; the stdio server prefers `MCP_API_KEY` and falls back to `API_KEY` — that separation lets you give a local session a different key than production.
+
+Missing key returns:
+
+```
+Write access denied. Connect with an Authorization: Bearer <API_KEY> header.
+```
+
+## Verify it works
+
+```bash
+curl https://cs.example.com/.well-known/mcp
+```
+
+Then, over the wire:
+
+```bash
+curl -X POST https://cs.example.com/api/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -D headers.txt \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'
+
+SESSION_ID=$(grep -i 'mcp-session-id:' headers.txt | tr -d '\r' | awk '{print $2}')
+
+curl -X POST https://cs.example.com/api/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Mcp-Session-Id: $SESSION_ID" \
+  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
+```
+
+`tools/list` returning a populated array is the real test — clients vary in whether they call it automatically.
+
+Interactive docs are at `https://cs.example.com/docs`, where every tool's schema can be exercised in the browser.
+
+## Troubleshooting
+
+| Problem | Fix |
+|---|---|
+| Server not listed | Restart the client after editing config; check JSON syntax |
+| "Session not found" | Re-initialize. Sessions expire after an hour idle |
+| "Missing Mcp-Session-Id" | Use the Streamable HTTP transport, not SSE |
+| Tools empty | Call `tools/list` after `initialize` |
+| "Write access denied" | Add the `Authorization` header |
+| Connection refused (local) | `bun run mcp` must be running, `DATABASE_URL` reachable |
+
+Sessions are pruned after an hour of inactivity, and each session gets its own server instance. CORS is enabled for browser-based clients.
+
+## Beyond the tools
+
+Connecting MCP does not give an agent product judgement — it gives it typed access. Anything about *how* to operate the channel (media limits, what a short is, when to pin) belongs in a skill, installed with `ds-cs add`. The combination is the point: tools for capability, skills for conduct.

package/skills/product/post-with-media/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: post-with-media
+description: Create, read, edit, pin and delete posts on a live DS-CS channel over the REST API — including the two-step media upload and the exact request shapes. Use when an agent needs to publish content, list or search existing posts, pin a post, or clean one up. For stories use manage-stories; for realtime delivery use webhooks.
+---
+
+# Working with posts
+
+## Connection
+
+```
+Base URL:  https://<your-channel>
+Auth:      Authorization: Bearer <API_KEY>     (write operations only)
+```
+
+The API key is the `API_KEY` from the channel's `.env` (`openssl rand -hex 32` to generate one). **Reads are public — no key needed.** Writes (POST, PATCH, DELETE) require it, and are rate limited per IP and path (`API_KEY_RATE_LIMIT_MAX_REQUESTS`, default 30 per `API_KEY_RATE_LIMIT_WINDOW_MS`, default 60s).
+
+Set it up once:
+
+```bash
+ds-cs login --url https://cs.example.com --api-key "$API_KEY"
+```
+
+## Upload media first — always
+
+A post references media **by URL**. There is no inline base64 body. Upload, then reference the returned `url`.
+
+**Server-side (curl, agents, MCP — simplest):**
+
+```bash
+curl -X POST https://cs.example.com/api/upload \
+  -H "Authorization: Bearer $API_KEY" \
+  -F "file=@photo.jpg"
+```
+
+Returns:
+
+```json
+{
+  "url": "https://…/media/image/9f8e….jpg",
+  "key": "media/image/9f8e….jpg",
+  "kind": "image",
+  "mimeType": "image/jpeg",
+  "size": 1234567,
+  "width": 1080,
+  "height": 1920,
+  "duration": 0,
+  "filename": "photo.jpg"
+}
+```
+
+**Direct browser-to-S3 (real upload progress):** `POST /api/upload/presign` with `{ filename, mimeType }` → `PUT` the file to the returned `uploadUrl` → `POST /api/upload/confirm` with `{ key, mimeType, filename, size, width, height, duration }` → the full media object. Prefer presign for large videos; the single-file endpoint buffers the whole thing in memory on the server.
+
+### Constraints
+
+| Kind | Max size | Allowed MIME |
+|---|---|---|
+| image | 10 MB | jpeg, png, webp, gif, avif, svg+xml |
+| video | 100 MB | mp4, webm, quicktime |
+| audio | 25 MB | mpeg, mp4, wav, ogg, aac, flac |
+| file | 25 MB | pdf, text/plain |
+
+Override with `MEDIA_MAX_IMAGE_SIZE_MB`, `MEDIA_MAX_VIDEO_SIZE_MB`, `MEDIA_MAX_AUDIO_SIZE_MB`, `MEDIA_MAX_FILE_SIZE_MB`, `MEDIA_ALLOWED_MIME_TYPES`. Validation failures come back as `MediaValidationError` with a specific message and status.
+
+## Create a text post
+
+```bash
+curl -X POST https://cs.example.com/api/posts \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"content":"Just shipped a new feature!"}'
+```
+
+Returns `201` with the created post.
+
+## Create a media post
+
+```bash
+curl -X POST https://cs.example.com/api/posts \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "content": "Studio clip",
+    "media": [
+      {
+        "url": "https://…/media/video/abc.mp4",
+        "type": "video",
+        "width": 1080,
+        "height": 1920,
+        "duration": 42
+      }
+    ]
+  }'
+```
+
+`type` is one of `text`, `image`, `video`, `voice`, `file`. `width`/`height` matter — the feed classifies a video as a **short** by aspect ratio (9:16, filtered to 1.6–2.0), so a vertical video with no dimensions is never treated as a short.
+
+**Multiple media items create one post per item**, except when every item is an image, which produces a single carousel post. The response is the first post; use `list_posts` to find the others.
+
+## Read posts
+
+```bash
+GET /api/posts?page=1&limit=20            # paginated
+GET /api/posts?type=count                 # { "total": n }
+GET /api/posts?type=shorts                # vertical videos only
+GET /api/posts?search=photography         # free-text
+GET /api/posts/{post_id}                  # one post, with reactions
+```
+
+`limit` is capped at 100. List response shape:
+
+```json
+{
+  "items": [
+    {
+      "id": "b1a2c3d4-…",
+      "type": "list",
+      "content": "…",
+      "media": [{ "kind": "image", "url": "…", "width": 1080, "height": 1920 }],
+      "reactions": [{ "emoji": "❤️", "count": 12 }],
+      "views": 342,
+      "pinnedAt": null,
+      "postStatus": "sent",
+      "createdAt": "2026-08-23T10:15:00.000Z"
+    }
+  ],
+  "page": 1,
+  "limit": 20,
+  "total": 1,
+  "hasMore": false
+}
+```
+
+`views` is a display counter stored as a string — treat it as opaque and do not parse it as a number.
+
+## Edit and pin
+
+```bash
+curl -X PATCH https://cs.example.com/api/posts/$POST_ID \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"pinnedAt":"2026-08-21T00:00:00Z"}'
+```
+
+Partial update. Any of `content`, `views`, `pinnedAt`, `media`, `type`. Passing `pinnedAt: null` unpins. Pinned posts surface in a dedicated bar and at the top of the feed.
+
+## React and view
+
+```bash
+curl -X POST https://cs.example.com/api/posts/$POST_ID?action=reaction \
+  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
+  -d '{"emoji":"🔥"}'
+
+curl -X POST https://cs.example.com/api/posts/$POST_ID?action=view
+```
+
+`action=view` increments the counter and is public.
+
+## Delete
+
+```bash
+curl -X DELETE https://cs.example.com/api/posts/$POST_ID \
+  -H "Authorization: Bearer $API_KEY"
+```
+
+Permanent. There is no trash and no undo.
+
+## Via MCP instead
+
+If an MCP client is connected, prefer the typed tools — the server enforces auth and the schemas for you:
+
+| Tool | Auth | Purpose |
+|---|---|---|
+| `list_posts` | public | Paginated, searchable |
+| `get_post` | public | One post with reactions |
+| `create_post` | API key | Text or media post |
+| `update_post` | API key | Content / pin status |
+| `delete_post` | API key | Remove a post |
+
+Connect with `ds-cs mcp claude-code`, or point any client at `https://<channel>/api/mcp`.
+
+## Verify
+
+Discovery endpoint, useful for confirming a channel is alive:
+
+```bash
+curl https://cs.example.com/.well-known/mcp
+```
+
+Full REST reference is served at `https://cs.example.com/docs`, and the OpenAPI spec at `/openapi.json`.
+
+## Mistakes that cost time
+
+- Posting a URL that was never uploaded — the media silently renders broken.
+- Omitting `width`/`height` on a vertical video and wondering why it is not a short.
+- Expecting `update_post` to replace media — it is a partial patch; send the fields you mean to change.
+- Deleting by a guessed ID. `list_posts` first, then delete the exact `id` that came back.
+- Assuming reads need auth. They do not, and a 401 on a `GET` means your *key* is wrong, not that auth is required.