@rayul/kordis 0.3.1 → 0.5.0

package/assets/KORDIS.md

@@ -29,12 +29,13 @@ Verbs: `kordis search`, `info`, `read`, `pull`, `push`, `comment`, `star`,
 `unstar`, `whoami`/`login`/`logout`. ALWAYS pass `--json` when parsing
 programmatically.
 
-Detail lives in four on-demand sub-skills installed at `~/.claude/skills/`,
+Detail lives in five on-demand sub-skills installed at `~/.claude/skills/`,
 `~/.codex/skills/`, and `~/.gemini/skills/`:
 - `kordis-search` — find and browse packages
 - `kordis-using` — `read` vs `pull`, behaviour per package type, attribution
 - `kordis-publishing` — author and push packages
 - `kordis-social` — identity, session, comments, and stars
+- `kordis-recommend` — personalized menu (`kordis recommend`); use when the user signals discovery intent without a specific slug
 
 Tools with a SKILL.md description-matcher (Claude Code, Codex) auto-load
 these. Tools without one (e.g. Gemini): READ

package/assets/kordis-recommend/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: kordis-recommend
+description: Use whenever the user wants ideas — phrases like "any new stuff?", "recommend", "추천", "what should I try", "anything fresh?", "discover", "show me good skills", "what's popular for <stack>". Surfaces a personalized menu of Kordis packages the user may want to install or peek at. Read eagerly when the user signals discovery intent without a specific slug in mind.
+type: skill
+allowed-tools: ["Bash(kordis:*)"]
+---
+
+# Kordis: Personalized Recommendations
+
+## Goal
+Surface a ranked, agent-friendly menu of packages the user may want next.
+Algorithm is hybrid: content-based (your local stack) + item-CF (other
+users with similar installs) + popularity decay (stars + recency).
+
+## When to invoke
+
+Trigger any time the user signals discovery intent without naming a slug:
+
+- "anything new I should try?"
+- "추천 좀 해봐"
+- "what's a good skill for <topic>?"
+- "I'm setting up a Python project — anything good?"
+- "show me popular tools"
+- "discover something fresh"
+
+Do NOT invoke for specific lookups (use `kordis search` for those) or when
+the user names a slug (use `kordis info` / `kordis read`).
+
+## Command
+
+### `kordis recommend [--limit N] [--verbose] [--no-context] [--json]`
+
+| flag           | meaning                                                          |
+| -------------- | ---------------------------------------------------------------- |
+| `--limit <n>`  | max items (default 10, max 50)                                   |
+| `--verbose`    | include `score_breakdown` per item (content / cf / popularity)   |
+| `--no-context` | skip the `X-Kordis-Context` header for this call (one-shot opt-out) |
+| `--json`       | global flag — JSON envelope, no human render                     |
+
+Anonymous: works without login. Personalized signal rides on an opt-in
+`X-Kordis-Context` HTTP header (installed agent tools, top 3 CWD file
+extensions, framework hints from package.json/pyproject.toml/Cargo.toml,
+SHA-256-truncated hashes of installed slugs). Server uses it for in-flight
+re-ranking ONLY — never persisted (see CLAUDE.md "Telemetry / privacy").
+
+## Personalization opt-in
+
+The user is asked ONCE — at first interactive `kordis setup` OR (if
+postinstall ran in `--silent` mode) at first `kordis recommend`. Answer
+persists in `~/.kordis/config.json` (`personalization: 'on' | 'off'`).
+
+Override at runtime:
+- `KORDIS_NO_CONTEXT=1` env — no header for the entire shell session
+- `--no-context` flag — no header for this single call
+
+If the response field `personalized` is `false`, the server returned
+popularity-only results — surface this to the user so they know the
+recommendations aren't tailored.
+
+## Menu envelope (one item)
+
+```json
+{
+  "full_slug": "rayul/fastapi-router",
+  "title": "FastAPI Router",
+  "description": "Streaming response middleware for FastAPI apps.",
+  "type": "skill",
+  "tier": "A",
+  "current_version": "0.2.0",
+  "stars": 12,
+  "downloads": 87,
+  "install_command": "kordis pull rayul/fastapi-router",
+  "jit_read_command": "kordis read rayul/fastapi-router",
+  "why_recommended": "You have FastAPI locally; this package is relevant to that stack.",
+  "confidence": "high"
+}
+```
+
+`confidence` interpretation when surfacing to the user:
+
+| value    | how to surface                                                            |
+| -------- | ------------------------------------------------------------------------- |
+| `high`   | "You should try X" — both content match and co-install signal align       |
+| `medium` | "You might like X" — one signal strong                                    |
+| `low`    | "Worth a look — popular right now" — cold-start / no personalization      |
+
+## Steps
+
+### 1. Fetch menu
+`kordis recommend --limit 10 --json`. (Add `--no-context` ONLY if the user
+explicitly asked you not to share their stack.)
+
+### 2. Triage
+Filter mentally by `confidence`. If everything is `low` and `personalized`
+is `false`, tell the user personalization is off and they can enable it
+via `kordis setup` (re-asks the prompt on next interactive run).
+
+If the response carries `capped_by_author > 0`, ALSO surface a one-line
+note to the user — e.g. "N more candidates from the same publisher were
+skipped by the diversity cap" — so they understand why the list is
+shorter than the requested `--limit`. Without this hint users frequently
+mistake a short menu for a sparse or broken registry.
+
+### 3. Present
+Surface 3-5 picks max. For each, show: full_slug, one-line `why_recommended`,
+confidence wording per the table above, and the next-step
+`install_command` / `jit_read_command`. Do NOT dump the whole menu — agent
+should curate.
+
+### 4. Act
+If the user picks one:
+- "install it" → run `install_command` from the menu (already a complete
+  shell line)
+- "peek first" → run `jit_read_command`, summarize, then offer install
+- "tell me more" → `kordis info <full_slug>`
+
+## Examples
+
+<example>
+User: "any new tools I should try?"
+1. kordis recommend --limit 10 --json
+2. Filter to top 3 with confidence ≥ medium
+3. Show each with why_recommended + install_command
+4. Ask which to install or peek
+</example>
+
+<example>
+User: "추천 좀 해봐"
+1. kordis recommend --limit 10 --json
+2. If personalized is false, tell the user briefly + suggest `kordis setup`
+3. Surface 3-5 in Korean using the why_recommended verbatim (English is fine
+   — re-render the user-facing prose in Korean as needed)
+</example>
+
+<example>
+User: "I'm working on a Next.js project, anything useful for that?"
+1. kordis recommend --limit 10 --json    # context header carries 'next' framework hint
+2. Filter to packages whose why_recommended mentions Next.js
+3. Offer top 3 picks
+</example>
+
+## Reminder footer
+
+Other CLI commands (`kordis pull`, `kordis search`) may print a one-line
+hint like `→ N new recommendations match your stack: kordis recommend`.
+That's a signal that `~/.kordis/recommendations.json` cache has fresh,
+unseen picks. Running `kordis recommend` marks the set as seen and
+suppresses the footer until a new fetch generates fresh content.