docs(brand): align repo words with the curated registry position

GLOSSARY.md

@@ -22,6 +22,11 @@ Every public export, command, error, route, and document uses these terms.
 | Source status | lockfile and protocol | published value | skilld CLI, CI | source status |
 | Update relation | skilld CLI JSON v1 | published value | Agent, developer, CI | update relation |
 | Agent target | skilld CLI | published configuration | Agent | Agent target |
+| registry | skilld.dev | published surface | developer, Agent | registry |
+| curated | skilld.dev | published surface | developer | curated |
+| author | GitHub | external standard | skilld.dev, developer | author |
+| provenance | lockfile and protocol | published value | skilld CLI, developer | provenance |
+| lockfile | `.skills/skilld-lock.yaml` | published file | skilld CLI, CI | lockfile |
 
 | Identifier | Term |
 | --- | --- |
@@ -232,6 +237,56 @@ The Rust type for the second is `TransientSkill`, never `SkillRun`.
 
 **Casing:** `Outdated Skill report` in prose, `outdated` in commands.
 
+### registry
+
+**Is:** the curated index of Skills that skilld.dev publishes and the skilld CLI searches.
+
+**Use for:** the skilld.dev catalogue as a whole and `skilld search` results.
+
+**Never:** marketplace, store, hub, directory.
+
+**Casing:** `registry` in sentences, `skilld registry` when the owner matters.
+
+### curated
+
+**Is:** admitted to the registry by a person, with a reason that person can state.
+
+**Use for:** the registry and the Skills it lists.
+
+**Never:** approved, certified, vetted, official.
+
+**Casing:** `curated` in sentences.
+
+### author
+
+**Is:** the GitHub account or person who wrote a Skill in their own Repository.
+
+**Use for:** the credited writer of one Skill on every surface.
+
+**Never:** creator, publisher, contributor, owner in customer copy.
+
+**Casing:** `author` in sentences, `Author` in headings.
+
+### provenance
+
+**Is:** the recorded facts about where a Skill came from: Repository, commit, author, Artifact attestation, and source status.
+
+**Use for:** what `skilld verify` and the source status describe.
+
+**Never:** trust, safety, reputation, security.
+
+**Casing:** `provenance` in sentences.
+
+### lockfile
+
+**Is:** the `.skills/skilld-lock.yaml` file that records each installed Skill, its source, commit, digest, and source status.
+
+**Use for:** the file `skilld install` writes and restores.
+
+**Never:** manifest, lock, state file, config.
+
+**Casing:** `lockfile` in prose, `skilld-lock.yaml` for the file name.
+
 ## Banned
 
 | Never | Use instead | Why |

README.md

@@ -1,34 +1,74 @@
-<h1><a href="https://skilld.dev"><img src=".github/logos/logo-mark.svg" alt="" width="28" height="28" valign="middle"></a> skilld</h1>
+<h1>skilld</h1>
 
 [![npm version](https://img.shields.io/npm/v/skilld?color=yellow)](https://npmjs.com/package/skilld)
 [![npm downloads](https://img.shields.io/npm/dm/skilld?color=yellow)](https://npm.chart.dev/skilld)
-[![license](https://img.shields.io/npm/l/skilld?color=yellow)](https://github.com/skilld-dev/skilld/blob/main/LICENSE)
+[![license](https://img.shields.io/github/license/skilld-dev/skilld?color=yellow)](https://github.com/skilld-dev/skilld/blob/main/LICENSE)
 
-Search, run, install, and keep Agent Skills current.
+> 🪶 Curated agent skills by humans. Search, run, install, and keep them current. One command, every Agent.
 
-skilld v3 has two products:
+<a href="https://skilld.dev"><picture><source media="(prefers-color-scheme: dark)" srcset=".github/logos/logo-mark.svg"><img src=".github/logos/logo-mark-light.svg" alt="skilld logo" width="120"></picture></a>
 
-- The native `skilld` CLI manages Skills.
-- The JavaScript [`skilld-harness`](./packages/harness) package runs visible Skill generation and review instructions.
+<p align="center">
+<table>
+<tbody>
+<td align="center">
+<sub>Made possible by my <a href="https://github.com/sponsors/harlan-zw">Sponsor Program 💖</a><br> Follow me <a href="https://twitter.com/harlan_zw">@harlan_zw</a> 🐦 • Join <a href="https://discord.gg/275MBUBvgP">Discord</a> for help</sub><br>
+</td>
+</tbody>
+</table>
+</p>
 
-The skilld CLI contains no Skill generation logic or Agent runtime.
+## Features
 
-## Install the skilld CLI
+- 👤 **Every Skill has a human author.** A maintainer wrote it in their own GitHub Repository. skilld.dev lists it under their name with a link to the source file.
+- 📖 **Read before you run.** `skilld run` prints `SKILL.md` and installs nothing. Your Agent follows it for this session only.
+- 🔁 **Know when the source moved.** skilld records the source commit. `skilld update --check` reports each update relation, and `skilld outdated` lists what fell behind.
+- 🎯 **One command, every Agent.** `skilld install` detects your Agent targets. Claude Code, Codex, Cursor, Gemini CLI, and the rest get the same Skill.
+- 🔏 **Verified delivery.** skilld.dev builds an immutable Artifact from an exact commit. The CLI checks its digest and attestation before it writes a file.
+- 🦀 **Native binary, no runtime.** The npm package selects a native executable for your system. No JavaScript engine, no fallback.
+
+## What is skilld?
+
+skilld is a curated registry of agent Skills that real maintainers wrote in their own GitHub repositories, usable with one command in every Agent.
+
+A Skill is a directory with a `SKILL.md` file in the [Agent Skills](https://agentskills.io) format.
+Install-count leaderboards and generated doc dumps tell you a Skill is popular.
+skilld tells you who wrote it, links the exact file, and tracks the commit it came from, so you can read it before your Agent follows it.
+
+The `skilld` CLI searches, runs, installs, updates, verifies, and removes Skills.
+It contains no Skill generation logic and no Agent runtime.
+Skill authoring lives in visible [skilld-maintained Skills](#author-a-skill) and the optional [Harness](#harness).
+
+See how skilld compares with skills.sh and Context7: [skilld.dev/vs/skills-sh](https://skilld.dev/vs/skills-sh).
+
+## Get Started
+
+Install the CLI:
 
 ```sh
 npm install --global skilld
 ```
 
-The npm package selects a native executable for the current system.
-It has no JavaScript CLI engine or JavaScript fallback.
+Find a Skill, then run it for this session:
+
+```sh
+skilld search find-skill
+skilld run skilld:skilld-dev/skills/find-skill
+```
 
-Ask your Agent to run the skilld-maintained Skill for the current session:
+`skilld run` prints `SKILL.md` to stdout and writes no file.
+Ask your Agent to run the command and follow the printed instructions.
+If you run it yourself, pass the output to your Agent.
+
+Install the Skill when you want it in every session:
 
 ```sh
-skilld run skilld
+skilld install skilld:skilld-dev/skills/find-skill
 ```
 
-Install it only when you want your Agent to keep it across sessions:
+An install writes files. If an Agent runs the install, it asks you first.
+
+Teach your Agent the CLI with the skilld-maintained `skilld` Skill:
 
 ```sh
 skilld install skilld --global
@@ -44,75 +84,78 @@ skilld install skilld -g --agent kiro --agent zed
 skilld install skilld -g --agent all
 ```
 
-## Run a Skill without installing it
+### Selectors
 
-`skilld run` is the default way to use a Skill.
-It prints `SKILL.md` to stdout.
-Ask your Agent to run the command and follow the printed instructions.
-If you run it yourself, pass the output to your Agent.
+`skilld:OWNER/REPOSITORY/SKILL` names one Skill in the registry.
+`skilld search` prints the selector for each result.
+`skilld-dev/skills` is the Repository; `find-skill` is the Skill directory inside it.
 
-```sh
-npx skilld run skilld:skilld-dev/skills/vue
-```
-
-A remote run writes no Skill files.
-It creates no lockfile entry, Agent target, project file, or Skill cache.
-The command retains no Skill files after it exits.
+### Supporting files
 
 skilld names the supporting files a Skill carries and prints none of them.
 Read one when the instructions call for it:
 
 ```sh
-npx skilld run skilld:skilld-dev/skills/vue --revision <commit> --file references/api.md
+skilld run skilld:skilld-dev/skills/find-skill --revision <commit> --file references/api.md
 ```
 
 Use the revision and file-read command from the initial output.
 skilld never prints executable or binary files.
 A Skill that must run its own script needs an install.
 
-Install the Skill when you want it in every session:
-
-```sh
-skilld install skilld:skilld-dev/skills/vue
-```
-
-An install writes files. Ask the user first.
-
-## Use the skilld CLI
+## Commands
 
 ```sh
 # Find a Skill
-skilld search vue
+skilld search <query>
 
 # Run a Skill for this session only
-skilld run skilld:skilld-dev/skills/vue
+skilld run <selector>
 
 # Read one supporting file that Skill carries
-skilld run skilld:skilld-dev/skills/vue --revision <commit> --file references/api.md
+skilld run <selector> --revision <commit> --file <path>
 
-# Install a Skill in the current project
-skilld install skilld:skilld-dev/skills/vue
+# Install a Skill in the current project, or restore the lockfile
+skilld install <selector>
+skilld install
 
 # Inspect installed Skills
 skilld list
-skilld view vue
+skilld view <skill>
 
 # Keep Skills current
-skilld verify vue
-skilld update vue
-
-# Check update relations for an Agent or CI
+skilld outdated
 skilld update --check --json
+skilld update <skill>
+skilld verify <skill>
 
 # Remove a Skill
-skilld remove vue
+skilld remove <skill>
 ```
 
 Project installs update `.skills/skilld-lock.yaml` and the selected Agent targets.
-Use `--global` for account level Agent targets.
+Use `--global` (or `-g`) for account level Agent targets.
+Use `--agent <agent>` to name a target; repeat it for several, or use `--agent all`.
 Use `--mode copy` or `--mode symlink` to control target writes.
+Use `--json` with `search`, `run`, and `update --check` for stable output.
+
+Run `skilld install --help` for every Agent target value.
+
+## Author a Skill
 
-Run `skilld install` without a source to restore the lockfile state.
+Run the skilld-maintained `generate-package-skill` Skill, or the Harness, to bootstrap a draft Skill for a package you maintain.
+Edit the draft, commit it to your Repository, and own it from there.
+skilld lists it with your name and a link to the file.
+
+The skilld-maintained Skills:
+
+- [`skilld`](./skills/skilld): search, run, and install Skills with the CLI
+- [`generate-package-skill`](./skills/generate-package-skill): draft a Skill for a package you maintain
+- [`generate-project-skill`](./skills/generate-project-skill): draft a Skill from a project you maintain
+- [`review-skill`](./skills/review-skill): review a Skill before you publish it
+
+Direct Skill runs stay user reviewed.
+The instructions and changes stay visible to you.
 
 ## Artifact delivery
 
@@ -141,22 +184,20 @@ skilld install github:skilld-dev/skilld/skills/skilld --direct --agent codex
 ```
 
 The installed Skill receives the `unverified` source status.
-The user reviews the Skill before use.
+Review the Skill before use.
 
 Direct mode never handles private Repositories.
 It never falls back to skilld.dev.
 
-Generated commands use POSIX shell quoting on Unix.
-They use PowerShell quoting on Windows.
-
-## Source status
+### Source status
 
 - `verified`: skilld checked a skilld.dev Artifact and its attestation.
 - `local`: the Skill came from a local directory or a bundled skilld-maintained Skill.
 - `unverified`: direct mode fetched the Skill from public GitHub.
 
 `verified` describes provenance checks.
 It does not endorse the instructions inside a Skill.
+See [SECURITY.md](./SECURITY.md) for what skilld checks and how to report a problem.
 
 ## Account and configuration
 
@@ -173,39 +214,10 @@ skilld config list
 Native builds store account credentials in the operating system keychain.
 The CLI does not store tokens in environment variables or plain text files.
 
-## Generate or review a Skill
-
-Skill generation lives outside the skilld CLI.
-
-Use these skilld-maintained Skills directly with your Agent:
-
-- [`generate-package-skill`](./skills/generate-package-skill)
-- [`generate-project-skill`](./skills/generate-project-skill)
-- [`review-skill`](./skills/review-skill)
-- [`skilld`](./skills/skilld)
-
-Direct Skill runs remain user reviewed.
-The instructions and changes stay visible to the user.
+## Harness
 
 Use [`skilld-harness`](./packages/harness) when an application or CI needs strict output checks.
 The Harness runs the same visible Skill files through an AI SDK Harness.
-
-```sh
-pnpm add skilld-harness @ai-sdk/harness ws zod
-```
-
-```ts
-import { createSkillHarness } from 'skilld-harness'
-
-const skillHarness = createSkillHarness({ harness, sandbox })
-
-const result = await skillHarness.run({
-  _tag: 'PackageSkill',
-  source: { _tag: 'NpmPackage', spec: 'vue' },
-  destination: { rootDir: '.agents/skills', name: 'vue' },
-})
-```
-
 See the [`skilld-harness` guide](./packages/harness/README.md) for its full contract.
 
 ## Upgrade from v2
@@ -216,7 +228,7 @@ Back up v2 state before replacing the CLI.
 Follow the [v2 to v3 migration guide](./docs/migrate-v2-to-v3.md).
 It maps removed commands and explains rollback limits.
 
-## v3 development
+## Development
 
 ```sh
 pnpm install