@rayul/kordis 0.13.0 → 0.14.0

package/assets/kordis-memory/SKILL.md

@@ -0,0 +1,430 @@
+---
+name: kordis-memory
+description: Use when the user wants an answer from THEIR OWN notes folder rather than from the registry — connecting a notes/vault folder to Kordis, recalling what they previously decided, or expanding one recalled card into its detail. Triggers include "what did I decide about X", "check my notes", "예전에 뭐라고 정했더라", "내 노트에서 찾아줘", "connect my Obsidian vault", "link my notes folder", "볼트 연결", "rebuild the memory index", "kordis memory recall", "무슨 근거로 그렇게 정한 거였지". NOT for finding packages other people published — that is kordis-search.
+type: skill
+allowed-tools: ['Bash(kordis:*)']
+---
+
+# Kordis: Recall Over the User's Own Notes
+
+## Status — experimental, off unless the user turned it on
+
+Every command here exists only when `KORDIS_EXPERIMENTAL_MEMORY=1` is set in
+the environment. With the flag unset the whole surface is absent from
+`kordis --help`, and `kordis memory recall …` fails as an unknown command.
+
+That absence is deliberate: appearing in help is a promise, and this surface
+is not finished. If the commands are missing, **say the feature is off and
+stop** — do not set the variable on the user's behalf, and do not fall back to
+reading their notes folder yourself with Read/Grep. The point of the feature
+is that a human decides which files feed it; reaching around it defeats
+exactly the thing it exists to do.
+
+## Goal
+
+Answer a question from the user's own notes — decisions, specs, meeting
+records — without the notes being copied, moved, uploaded, or rewritten. Kordis
+builds a derived index OUTSIDE the folder (`~/.kordis/memgineering/<hash>/`)
+and treats the notes as the only source of truth. Deleting the index costs a
+rebuild and nothing else.
+
+This is the opposite direction from the rest of Kordis: `kordis search` finds
+what OTHER people published; this reads what the USER already wrote.
+
+## The consent rule — read before running anything
+
+`kordis memory link` is the one moment a human decides which of their files
+feed the index. Therefore:
+
+1. **Never run `link` unless the user asked for their notes connected in this
+   conversation.** Not implied by "help me remember", not implied by an earlier
+   session.
+2. **Run `--dry-run` first, always.** It builds nothing and prints the exact
+   sentences that would be stored. Show that to the user before proceeding.
+3. **Do not pass `--yes` on the user's behalf.** It skips the confirmation
+   prompt. Use it only when the user has already seen the `--dry-run` output
+   and told you to go ahead.
+
+`link` refuses files whose CONTENT looks like a credential, and reports them
+by path. When it does, relay the refusal — do not try to get the file indexed
+some other way.
+
+## Commands
+
+### `kordis memory link <path> [--dry-run] [--yes] [--json]`
+
+Audit a notes folder's exclusion rules, then index it.
+
+| flag        | meaning                                                     |
+| ----------- | ----------------------------------------------------------- |
+| `--dry-run` | print what WOULD be stored, then stop. Nothing is written.  |
+| `--yes`     | skip the confirmation prompt (only after the user approved) |
+
+### `kordis memory reindex [--vault <path>] [--json]`
+
+Discard the derived index and rebuild it from the notes. Use after the user
+changes their exclusion rules (`.memgdeny` / `.memgallow`), or when they want
+to see the audit summary again.
+
+### `kordis memory recall <query> [--vault <path>] [--scope <s>] [--limit <n>] [--json]`
+
+Recall memory cards for a question. `--limit` defaults to 8.
+
+Re-validates the index before answering, every time — a note edited a second
+ago is reflected. Unchanged files are confirmed by revision rather than
+re-read, so this is cheap enough to call whenever a question sounds like it
+has a prior answer.
+
+### `kordis memory card <handle> [--vault <path>] [--json]`
+
+Expand one `detail_handle` from `recall` into its claims and provenance. Pass
+the handle back verbatim — it looks like `recall://launch-date`.
+
+### `kordis memory propose --input <json> [--vault <path>] [--json]`
+
+Draft a change to a note. **Writes nothing.** See "Changing a note" below.
+
+`--input` takes a file path, `-` for stdin, or inline JSON with two keys:
+`candidate` (what to search with) and `commit` (the decision).
+
+### `kordis memory proposals [--state <state>] [--vault <path>] [--json]`
+
+List proposals waiting for the user's decision. Reading the list is also what
+applies expiry, since nothing runs in the background.
+
+### `kordis memory approve <id> [--yes] [--vault <path>] [--json]`
+
+Show the diff and, if the user agrees, write it. **This is the only command in
+the product that changes a user's note.**
+
+### `kordis memory reject <id> [--vault <path>] [--json]`
+
+Decline a proposal. The record is kept, not deleted.
+
+### `kordis memory retire <id> --reason <text> [--yes] [--vault <path>]`
+
+Mark a memory as no longer current. `<id>` is what a recall card prints after
+`recall://`. Writes ONE line into the note's `memgineering:` block —
+`status: retired` — and touches nothing else.
+
+**Retiring is not deleting, and the difference is the thing to relay.** The
+note keeps its prose and its conclusion, and recall keeps returning the card,
+ranked last and marked `[retired]`. A user who says "delete it" and then sees
+it in the next recall will think the command failed. Say which one they are
+getting.
+
+`kordis memory unretire <id> --reason <text>` reverses it.
+
+### `kordis memory exclude <path> [--yes] [--vault <path>]`
+
+Stop reading a note entirely. This is the one that makes a memory **disappear**
+from recall. It adds one line to the vault's `.memgignore` and does not change
+the note — not a byte.
+
+Takes a vault-relative file path, and refuses one that matches no file rather
+than writing a rule that silently protects nothing. To exclude a whole folder,
+the user edits `.memgignore` themselves.
+
+`kordis memory unexclude <path>` removes the line and the note is read again.
+
+### `kordis memory sync-rules [--yes] [--vault <path>]`
+
+Copies this vault's `.memgdeny` and `.memgignore` into `memgineering.md`, a
+visible file at the top of the notes folder. Deletes neither — both sources are
+merged.
+
+**Why it exists**: hidden files do not sync between machines. Obsidian Sync
+states it outright, and most vault sync behaves the same way. So the same
+folder opened on a second machine has all the notes and none of the
+protections, and nothing reports it: with no deny file there are no entries to
+report as unmatched.
+
+If `link` prints the "protect this machine only" warning, relay it and offer
+this command. Do not run it unprompted — it writes a file into their notes
+folder.
+
+### What travels between machines, and what does not
+
+| Travels (it is in the vault)         | Does not (it is machine-local)                          |
+| ------------------------------------ | ------------------------------------------------------- |
+| the notes themselves                 | the derived index — rebuild with `link` on each machine |
+| `status: retired` from `retire`      | **pending proposals**                                   |
+| `memgineering.md` after `sync-rules` | `.memgdeny` / `.memgignore` (hidden)                    |
+
+**A proposal is approved on the machine that drafted it.** Not seeing it
+elsewhere is not a bug and not something to work around — say so rather than
+re-drafting, which would leave two proposals for one change.
+
+### Which one does the user mean by "delete"?
+
+Ask, or offer both — they do different things and neither is undoable by the
+other:
+
+| They want                        | Command   | Result                                      |
+| -------------------------------- | --------- | ------------------------------------------- |
+| "that conclusion is out of date" | `retire`  | still recalled, ranked last, labelled       |
+| "stop reading that note"         | `exclude` | gone from recall; the file is untouched     |
+| the file itself gone             | _neither_ | that is their editor's job, not this tool's |
+
+Never run `exclude` when they asked to correct a conclusion — it hides the
+whole note, including everything else in it.
+
+### `kordis memory unlink [--purge] [--vault <path>] [--json]`
+
+Forget a vault: removes the registration, the derived index and pending
+proposals, and redacts finished ones. `--purge` deletes those records too.
+
+It does NOT remove changes already approved into the user's notes — those are
+their files. The output says so; relay it rather than implying a clean slate.
+
+### Which vault
+
+With exactly one linked folder, `--vault` is optional. With two or more,
+omitting it is an ERROR rather than a guess, because answering from the wrong
+folder is indistinguishable from answering wrongly. The error names the linked
+paths; pick with the user, don't guess.
+
+## Two tiers — cards first, detail only when needed
+
+`recall` returns CARDS: `id`, `title`, `summary`, `confidence`, `freshness`,
+`detail_handle`. It deliberately withholds the note bodies. That is what makes
+it affordable to call on an ordinary turn.
+
+Do NOT call `card` on every handle you got back. Read the summaries, decide
+which one actually answers the question, and expand only that one.
+
+`confidence` is `stated` when the note declared a claim in frontmatter and
+`inferred` when Kordis derived the card from the note's prose. Say which you
+are relying on when it matters — "your note says" is a different claim from
+"your note seems to say".
+
+## Contradictions are surfaced, never resolved
+
+When two notes disagree, `recall` returns both AND a `conflicts` entry naming
+them. It does not pick a winner, and neither should you.
+
+Show both sides with their `freshness` (`current` / `superseded`) and let the
+user decide. Silently preferring the newer note is how a memory system starts
+confidently reciting something its owner already changed their mind about.
+
+## What gets refused, and how the user overrides it
+
+Three separate nets, in increasing strength:
+
+| net         | what it catches                        | override                       |
+| ----------- | -------------------------------------- | ------------------------------ |
+| name        | filenames containing sensitive words   | `.memgallow`                   |
+| content     | file bodies that look like credentials | `.memgallow` (exact path only) |
+| `.memgdeny` | paths the user listed explicitly       | none — edit the file           |
+
+`.memgdeny` takes plain relative paths, one per line, **no glob syntax**. A
+line that matches no file protects nothing, so `link` blocks on an unmatched
+entry and suggests where that filename actually lives — relay the suggestion
+rather than telling the user to delete the line.
+
+## Steps
+
+1. Confirm the flag is on. `kordis memory recall --help` failing as an unknown
+   command means the feature is off — report that and stop.
+2. If nothing is linked yet, the error says so. Ask the user whether to connect
+   a folder; if yes, run `link --dry-run <path>` and show them the result.
+3. Run `kordis memory recall "<the user's question>" --json`.
+4. Read the cards. If `conflicts` is non-empty, present both sides.
+5. Expand at most the one or two handles that actually answer the question with
+   `kordis memory card <handle> --json`.
+6. Answer in the user's language, citing `provenance.sourcePath` so they can
+   open the note themselves.
+7. Zero cards is a clean signal. Say nothing matched and suggest broader words
+   or dropping `--scope`. Never fill the gap from your own memory of earlier
+   turns and present it as their note.
+
+## Examples
+
+### Recall with a contradiction present
+
+```
+$ kordis memory recall "when is the launch"
+Launch date
+  Moved the launch to 15 April after the supplier slipped a week.
+  stated · recall://launch-date
+Pricing
+  Settled on 4,500 KRW for the americano; cost is about 900.
+  inferred · recall://decisions/pricing.md
+Launch date (first plan) [superseded]
+  Agreed 20 March with the team.
+  stated · recall://launch-date-march
+
+⚠ 1 contradiction(s):
+  launch-date (active) ↔ launch-date-march (superseded)
+  Both sides are shown above — neither was hidden.
+```
+
+The right answer here names 15 April AND mentions that an earlier note said
+20 March and is marked superseded.
+
+### The same call as an agent should make it
+
+```
+$ kordis memory recall "when is the launch" --json
+{"memory_cards":[{"id":"launch-date","title":"Launch date","summary":"Moved the launch to 15 April after the supplier slipped a week.","confidence":"stated","freshness":"current","detail_handle":"recall://launch-date"}, …],"related":[],"conflicts":[{"between":["launch-date","launch-date-march"],"status":["active","superseded"]}]}
+```
+
+### Dry-run before connecting anything
+
+```
+$ kordis memory link ~/notes --dry-run
+
+Nothing was indexed. This is what WOULD be stored:
+
+  Launch date
+    Moved the launch to 15 April after the supplier slipped a week.
+    from decisions/launch-date.md
+
+  3 note(s). Run without --dry-run to index them.
+```
+
+### A refusal, reported rather than worked around
+
+```
+$ kordis memory link ~/notes --yes
+✓ indexed 3 note(s)
+  index: ~/.kordis/memgineering/c04f8eedc9723bcc
+  1 note(s) refused — their CONTENT looks like a credential:
+    private/server access.md  (labelled_credential)
+    Redact the file, or list it in .memgdeny to stop being asked.
+```
+
+## Changing a note
+
+A change to a user's note is a PROPOSAL until a human approves it. You draft;
+they decide. This is not a workflow preference — the notes are theirs, and
+they are the only one who can say whether their file should change.
+
+### The rules, in order of how badly they go wrong
+
+1. **Never run `approve --yes` unless the user said yes in this conversation.**
+   Not implied by "keep my notes up to date", not carried over from an earlier
+   session, not implied by them approving a different proposal. `--yes` skips
+   the prompt, and the CLI cannot tell your keystroke from theirs — this rule
+   is the only thing standing there.
+2. **Show the diff before asking.** Run `approve` without `--yes` so the user
+   sees the exact lines, or print the `before`/`after` from `propose --json`.
+   "I'll update your note" is not a description of a diff.
+3. **Do not re-approve after a conflict without showing the new diff.** If
+   `approve` reports the note changed, their earlier yes applied to a version
+   that no longer exists.
+4. **Propose freely; it writes nothing.** Drafting is cheap and reversible, so
+   when a conversation settles something the notes contradict, propose. Just
+   never confuse having drafted with having changed.
+
+### Drafting one
+
+```json
+{
+  "candidate": {
+    "subject": "launch date",
+    "scope": "decisions",
+    "candidate_claim": "The launch moved to 15 April."
+  },
+  "commit": {
+    "action": "supersede",
+    "memory_id": "launch-date",
+    "claim": {
+      "text": "The launch is on 15 April.",
+      "summary": "The launch is on 15 April.",
+      "confidence": "stated"
+    },
+    "reason": "The supplier slipped a week.",
+    "source_excerpt": "Agreed 20 March with the team.",
+    "target_path": "decisions/launch-date.md"
+  }
+}
+```
+
+`action` is one of:
+
+| action      | when                                                    |
+| ----------- | ------------------------------------------------------- |
+| `create`    | nothing on this subject exists yet                      |
+| `reinforce` | same conclusion, more support                           |
+| `supersede` | the conclusion changed — the old one is over            |
+| `conflict`  | two things disagree and you are NOT deciding which wins |
+| `ignore`    | not worth remembering; nothing is stored                |
+
+Notes on the fields, each of which is enforced:
+
+- **`summary` is required for `create` and `supersede`.** Recall searches and
+  displays the summary, never the claim text, so a change without one is
+  applied and then invisible.
+- **`source_excerpt` is required.** It is what the person approving reads to
+  judge whether you understood their note. Quote them, don't paraphrase.
+- **`memory_id` must come from what `propose` found.** You cannot change a
+  memory the search never surfaced.
+- **You do not name the version being changed.** It comes from what the search
+  read, so there is no field for it and nothing to invent — a write based on a
+  version nobody read is exactly what this prevents.
+
+### What a patch may touch
+
+Only the `memgineering:` block in the note's frontmatter, and within it only
+the conclusion (`claim`, `summary`, `contradicts`, `valid_from`,
+`updated_at`). The prose body is never edited, and the author's other
+frontmatter keys — including their comments — are carried through.
+
+Two things about the block are normalised rather than preserved byte for byte,
+and it is better to say so than to promise more than holds: a comment's
+alignment padding collapses to one space, and a block written as a one-line
+flow mapping is re-emitted as indented keys. Both keep every key and value.
+
+If a user asks you to rewrite the body of a note, do it with your normal file
+tools and say so plainly — that is a different act from recording a memory,
+and it does not go through this approval flow.
+
+## How a note states a claim
+
+Cards are `inferred` from prose unless the note declares one. Everything Kordis
+reads lives under a `memgineering:` key, so a note's own top-level `type:` or
+`status:` is never mistaken for an instruction to this tool:
+
+```yaml
+---
+memgineering:
+  id: launch-date
+  claim: The launch is on 15 April.
+  contradicts: [launch-date-march]
+---
+```
+
+`contradicts` is what makes two notes surface as a conflict.
+
+## Over MCP
+
+The same surface is available as MCP tools when the Kordis MCP server runs
+over **stdio** with the experimental flag set — `memory_recall`, `memory_card`
+and `memory_propose`. Tool names and arguments mirror the commands above.
+
+Two things are deliberately different there:
+
+- **There is no approve tool.** MCP has no interactive prompt, so one could
+  only behave like `--yes`. The user opens a terminal to decide; the tool
+  result tells them the exact command.
+- **The hosted endpoint never has these tools.** A hosted MCP server is one
+  process serving many people, and the notes it could reach belong to whoever
+  runs it. If you are talking to Kordis over a remote MCP endpoint and no
+  memory tools appear, that is correct and not a misconfiguration.
+
+## Limitations
+
+- **Writes only through an approval.** `approve` is the one command that
+  changes a note, and only after a human answers the prompt. Everything else
+  here reads. See "Changing a note" for what you may and may not do.
+- **Titles, aliases and summaries are searched** — not full note bodies. A
+  question whose words appear only deep inside a note will not match.
+- **The content scanner is shape-based.** It catches labelled credentials
+  (`password: …`, `비번은 …`) and known key formats, but a passphrase written
+  as ordinary prose reads as ordinary prose. It is a safety net, not a
+  guarantee — never tell the user their secrets are certainly excluded.
+- **Personal information generally is not a credential** and no net catches it.
+  Diagnoses, salaries, relationships in a note WILL be summarised into the
+  index. That is what the `--dry-run` screen is for.
+- Local folders only. No hosted, Git, or Notion backend yet.

package/assets/kordis-recommend/SKILL.md

@@ -2,12 +2,13 @@
 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:*)"]
+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).
@@ -28,14 +29,18 @@ the user names a slug (use `kordis info` / `kordis read`).
 
 ## Command
 
-### `kordis recommend [--limit N] [--verbose] [--no-context] [--json]`
+### `kordis recommend [--limit N] [--no-context] [--json]`
 
-| flag           | meaning                                                          |
-| -------------- | ---------------------------------------------------------------- |
-| `--limit <n>`  | max items (default 10, max 50)                                   |
-| `--verbose`    | include `score_breakdown` per item (content / cf / popularity)   |
+| flag           | meaning                                                             |
+| -------------- | ------------------------------------------------------------------- |
+| `--limit <n>`  | max items (default 10, max 50)                                      |
 | `--no-context` | skip the `X-Kordis-Context` header for this call (one-shot opt-out) |
-| `--json`       | global flag — JSON envelope, no human render                     |
+| `--json`       | global flag — JSON envelope, no human render                        |
+
+`--verbose` still parses but does nothing. It used to print each item's
+score components; the ranking blend is server-private, so there is no
+per-item score to surface. Rank order is the signal — do not tell the user
+a package's numeric score, because you no longer receive one.
 
 Anonymous: works without login. Personalized signal rides on an opt-in
 `X-Kordis-Context` HTTP header (installed agent tools, top 3 CWD file
@@ -56,6 +61,7 @@ The user is asked ONCE. Three paths persist the answer to
    Use this when the user has confirmed consent in chat — see Step 2.5.
 
 Override at runtime (does not change the persisted answer):
+
 - `KORDIS_NO_CONTEXT=1` env — no header for the entire shell session
 - `--no-context` flag — no header for this single call
 
@@ -85,27 +91,31 @@ Surface this AND ask the user before flipping the flag (Step 2.5).
 
 `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      |
+| 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`, follow Step 2.5 to offer the user a one-click consent path.
 
-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.
+If the menu is shorter than the requested `--limit`, that now means the
+registry genuinely has fewer candidates — compare against `total_candidates`
+and say so plainly rather than implying the tool is broken. The per-author
+diversity cap no longer shortens the menu: it reorders, pushing a publisher's
+surplus down instead of discarding it, so `capped_by_author` is always `0`.
+(It used to drop them, which capped every menu at 3 items regardless of
+`--limit`.)
 
 ### 2.5. Offer personalization consent (when `personalized: false`)
 
@@ -132,13 +142,16 @@ optionally via `kordis setup --personalization off` so the question
 isn't asked again.
 
 ### 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

package/assets/kordis-search/SKILL.md

@@ -70,8 +70,9 @@ array.
 ### 3. Triage the results
 
 - Prefer `review_status: passed`, higher `stars`, then `tier: A`.
-- For trending results, the `trending_score` field is populated — surface it
-  when comparing.
+- For trending results, **rank order is the signal** — the server returns no
+  numeric score, so never quote or compare one. Say "3rd on the 7-day
+  trending board", not a number.
 - IMPORTANT: if results are 0, RELAX one filter at a time before giving up.
   **Drop `--tool` first** — many published packages have an empty
   `tools_compatible` field, so `--tool <name>` undercounts hard. Then drop
@@ -125,7 +126,7 @@ User: "any Cursor-compatible package for code review?"
 <example>
 User: "what's trending on Kordis this week?"
 - kordis search --trending --window 7d --json
-- show top 5–10 with their `trending_score`; do NOT fetch bodies unless asked
+- show top 5–10 in the order returned; do NOT fetch bodies unless asked
 </example>
 
 <example>

package/assets/kordis-social/SKILL.md

@@ -66,13 +66,30 @@ response shape is the same whether the call newly starred or no-op'd; if the
 user wants to verify a NEW star landed, compare `stars` from `kordis info
 <full_slug> --json` before and after.
 
+**You cannot star a package the user authored.** The server refuses it with
+`not_authorized` (exit 11) — a star is a reader's endorsement and feeds
+ranking, so authors starring their own work would just be voting for
+themselves. This is a rule, not a glitch: do not retry, do not try another
+route, and do not present it as a failure the user should work around. Say
+what it is in one line and move on.
+
+<example>
+User: "star my rss-reader package"
+- kordis star rayul/rss-reader --json   -> exit 11, not_authorized
+- "본인이 올린 패키지엔 별점을 누를 수 없어요 — 별점은 읽은 사람의 추천이라
+   순위에 들어가서요. 슬러그를 공유하시면 다른 분이 누를 수 있습니다."
+- do NOT retry, do NOT suggest a second account
+</example>
+
 ### `kordis unstar <full_slug> [--json]`
 
 Remove your star. Idempotent — silent no-op when not previously starred.
 Auth required.
 
-Stars feed `--sort stars` ordering on `kordis search` and contribute to the
-`trending_score`.
+Stars feed `--sort stars` ordering on `kordis search` and the trending board.
+Only stars from someone **other than the author** count toward ranking. The
+numeric trending score is server-private and is no longer returned — rank
+order is the signal, so never quote a package's score to the user.
 
 ## Steps
 
@@ -130,6 +147,8 @@ User: "report that the v0.3.0 release of foo/bar is broken on macOS"
 User: "star foo/bar"
 - kordis star foo/bar --json
 - show new star count
+- if it returns `not_authorized` (exit 11), the user authored it — say so
+  in one line, do not retry
 </example>
 
 <example>

package/assets/kordis-using/SKILL.md

@@ -255,6 +255,12 @@ starring needs a one-click browser login; if they decline, drop it. NEVER run
 initiative. Caps: at most ONE offer per session, never twice for the same
 package, and a "no" suppresses all further offers that session.
 
+Do NOT offer for a package the USER themselves authored — the server refuses
+it with `not_authorized` (exit 11), because a star is a reader's endorsement
+and feeds ranking. Check the owner segment of the slug against `kordis
+whoami` before offering. If you offer anyway and it fails, say so once and
+drop it; do not retry.
+
 <example>
 User: "thanks, that fixed the parsing!"
 - reply ends: "following alice/pdf-extract@1.2.0 — want me to star it on Kordis?"