fix(copy): align site copy with v3 run-first positioning

.claude/context/brand-guidelines.md

@@ -16,7 +16,7 @@ Skills are knowledge, not packages, and knowledge has an author. A skill is wort
 
 ### Two loops
 
-- **Loop 1 — Activation:** anonymous discovery → install. Land, copy, run. No friction.
+- **Loop 1 — Activation:** anonymous discovery → run. Land, copy, run. No friction. Install is the opt-in second step.
 - **Loop 2 — Retention:** sign in with GitHub, watch your stack, get a weekly digest of what changed.
 
 ## Positioning
@@ -25,7 +25,7 @@ Skills are knowledge, not packages, and knowledge has an author. A skill is wort
 - A curated registry of AI agent skills written by real people in their own GitHub repos
 - A provenance layer: every skill links back to the repo and the maintainer who wrote it
 - Organization-owned skills stay in the registry and stay searchable. The homepage leads with skills by identifiable people because provenance is the point, but org skills are ranked lower, not excluded
-- One install command, every agent: `npx skilld add gh:owner/repo`
+- One command, every agent: `npx skilld@beta run skilld:owner/repo/skill` to use a skill now, `npx skilld@beta install skilld:owner/repo/skill` to keep it
 - A watch-for-changes layer: sign in with GitHub, get a digest when watched repos change
 
 ### What we are not
@@ -59,24 +59,24 @@ The pitch: Context7 gives you docs. skills.sh gives you a leaderboard. Skilld gi
 | Term | Definition | Usage notes |
 |------|-----------|-------------|
 | **skill** | A SKILL.md file that gives an AI agent domain knowledge | Lowercase always. Not "plugin", "extension", or "module" |
-| **package skill** | A skill tied to a specific npm package, bootstrapped with `skilld author` and owned, edited, and published by its maintainer in their own repo | Never platform-authored; the platform publishes no skills (VISION anti-scope 1) |
+| **package skill** | A skill tied to a specific npm package, drafted with the skilld-maintained `generate-package-skill` Skill and owned, edited, and published by its maintainer in their own repo | Never platform-authored; the platform publishes no skills (VISION anti-scope 1) |
 | **guide skill** | A curation tag on skilld.dev for skills not tied to a package | Distributed as git skills, tagged for filtering in browse views |
 | **collection** | A curated bundle of skills assembled by a collection author | Not "preset", "pack", "bundle", or "kit" in UI (fine in marketing prose) |
 | **author** / **curator** | A developer who maintains one or more collections on skilld. Identity is their GitHub login. | Either word is fine; "curator" reads warmer in editorial copy, "author" in product UI |
 | **registry** | skilld.dev, the central hub for curated agent skills | Also hosts the MCP server |
-| **install** | Adding a skill or collection to your agent's configuration | Not "download". `skilld add` is the canonical CLI verb |
+| **run** | Handing the agent a skill for the current session. `skilld run` prints the skill and writes no file | The default verb. Every skill surface leads with the run command. Not "try", "preview", "use once", or "ephemeral" |
+| **install** | Adding a skill or collection to your agent's configuration as local files | Not "download", not "add". `skilld install` is the opt-in second step, for a skill worth keeping in every session |
 | **agent** | The coding tool that reads skills: Claude Code, Codex, Cursor, Gemini CLI, and the rest of the CLI's targets | Not "client", "tool", "editor", or "IDE". Say "your agent" in UI; name a specific agent only inside the setup picker |
 | **project install** | Installing into the current repository, the default | UI label: "Project". Not "local" |
 | **global install** | Installing into the agent's home directory, so every project sees the skill | UI label: "Global". Not "system-wide" |
-| **use once** | Pasting a prompt that points the agent at the published SKILL.md, so it reads and follows the skill without writing files | UI label: "Use once". Not "try", "preview", or "ephemeral". Only offered where a public markdown URL exists |
 | **watch** | Subscribing to a repo or collection so you receive digest emails when it changes | The Loop 2 verb. Not "follow", not "star", not "subscribe" |
 | **digest** | Periodic email summarizing changes to your watched repos | Weekly default; daily and off are options |
 | **weekly** | The one email everyone gets: skills you liked that changed, plus what trended | Lowercase, "the weekly". Not "newsletter", "roundup", or "trending digest". Opt-out, on by default. Sits beside **digest**, which is the separate watched-repo email |
 
 ### Feature naming
 - Name features descriptively, not cleverly. "Stack selector" not "StackMatch"
 - No trademark-style capitalization for features (not "Smart Collections")
-- CLI commands use lowercase: `skilld add`, `skilld update`, `skilld author`
+- CLI commands use lowercase: `skilld run`, `skilld install`, `skilld update`
 
 ## Voice & Tone
 

GLOSSARY.md

@@ -0,0 +1,159 @@
+# Glossary
+
+Canonical vocabulary for skilld.dev. Every user-visible string, public API name, doc heading, and route segment uses these terms and no synonyms.
+
+Shared terms match the skilld CLI glossary (`skilld-dev/skilld/GLOSSARY.md`). That file wins for CLI commands, protocol types, and source status values. Voice and tone live in `.claude/context/brand-guidelines.md`.
+
+## Map
+
+| Term | Owner | Relation | Customer word |
+| --- | --- | --- | --- |
+| Skill | GitHub Repository, `layers/registry` | Repository 1—N Skill | "skill" |
+| Agent | the user's tool | Agent 1—N Agent target | "your agent" |
+| Repository | GitHub | Repository 1—N Skill | "repository" |
+| Artifact | skilld.dev API | Skill commit 1—1 Artifact | not shown |
+| source status | lockfile, skilld.dev API | Artifact 1—1 source status | "Verified", "Unverified", "Local" |
+| run | skilld CLI | Skill 1—1 run command | "run" |
+| install | skilld CLI | Skill 1—1 install command | "install" |
+| lockfile | skilld CLI | project 1—1 lockfile | "lockfile" |
+| curator | `layers/collections`, `/@login` | curator 1—N collection | "curator" |
+| collection | `layers/collections`, `/@login/slug` | collection N—N Skill | "collection" |
+| watch | `layers/identity` | account N—N Repository or collection | "watch" |
+| digest | `layers/identity` email | account 1—1 digest schedule | "digest" |
+| trending | `/skills/trending`, ADR-0004 | Repository 1—N social mention | "trending" |
+| registry | skilld.dev | one | "skilld" |
+| provenance | Skill detail, cards | Skill 1—1 author and source link | "written by", "source" |
+
+Collisions
+
+- "Verified" names a source status only. Never a safety claim, never a sync time.
+- "curator" and "author" both surface on profile pages. A curator assembles collections. An author writes a Skill.
+
+## Terms
+
+### Skill
+
+**Is:** a directory with a `SKILL.md` that follows the Agent Skills specification, written by a maintainer in their own Repository.
+
+**Never:** prompt, plugin, extension, module, guide.
+
+**Casing:** `Skill` in new product prose. Existing UI uses lowercase `skill`; see Open questions.
+
+### Agent
+
+**Is:** the coding tool that reads Skills: Claude Code, Codex, Cursor, Gemini CLI, and the rest of the CLI's targets.
+
+**Never:** client, tool, editor, IDE.
+
+**Casing:** `Agent` in prose, "your agent" in UI.
+
+### Repository
+
+**Is:** a GitHub repository that contains one or more Skills. The source of truth.
+
+**Never:** package host, registry entry. `repo` stays in identifiers and existing UI labels.
+
+### Artifact
+
+**Is:** immutable Skill bytes resolved from one exact source commit, delivered by the skilld.dev API to the skilld CLI.
+
+**Never:** hosted Skill, registry package, upload.
+
+### source status
+
+**Is:** the recorded provenance state for an installed Skill: `verified`, `local`, or `unverified`.
+
+**Use for:** the receipts panel and lockfile values. "Verified" means the Artifact attestation checked out.
+
+**Never:** safety state, trust score, "verified safe", a sync timestamp.
+
+### run
+
+**Is:** `skilld run`. The Agent reads the Skill for the current session and nothing lands on disk. The default command on every Skill surface.
+
+**Never:** try, preview, use once, ephemeral.
+
+### install
+
+**Is:** `skilld install`. Skill files land in the project and the lockfile records them. The opt-in second step.
+
+**Never:** add, download.
+
+### lockfile
+
+**Is:** the file the skilld CLI writes to record installed Skills, their commits, and source status.
+
+**Never:** manifest, registry file.
+
+### curator
+
+**Is:** a developer who assembles one or more collections. Identity is their GitHub login at `/@login`.
+
+**Use for:** collection pages, the `/community` directory, "Browse curators".
+
+**Never:** creator, publisher (for a person), "the Community" as a proper noun.
+
+### collection
+
+**Is:** a curated set of Skills assembled by a curator, with a reason per Skill, at `/@login/slug`.
+
+**Never:** preset, pack, bundle, kit, stack (in UI).
+
+### watch
+
+**Is:** subscribing to a Repository or collection so the digest reports its changes. The Loop 2 verb.
+
+**Never:** follow, star, subscribe, sync.
+
+### digest
+
+**Is:** the email that summarises changes to watched Repositories. Weekly by default; daily and off are options.
+
+**Never:** newsletter, notification, alert. "the weekly" is the separate opt-out email.
+
+### trending
+
+**Is:** Skills ranked by devs talking about them on X and Bluesky (ADR-0004). Never by installs.
+
+**Never:** popular, hot, top, leaderboard.
+
+### registry
+
+**Is:** skilld.dev, the curated index of Skills and the discovery MCP server.
+
+**Never:** marketplace, store, hub, catalog (in UI).
+
+### provenance
+
+**Is:** who wrote a Skill and the exact `SKILL.md` in their Repository. The quality signal.
+
+**Use for:** "written by {user}" on user pages, "published by {org}" on organization pages, source links.
+
+**Never:** trust score, verification tier, "curated by" for an author.
+
+## Banned
+
+| Never | Use instead | Why |
+| --- | --- | --- |
+| follow | watch | One Loop 2 verb |
+| sync (user-facing) | import (stars), "Checked GitHub {ago}" (freshness) | Internal jargon; say what happened |
+| use once, try, preview | run | One name for the transient path |
+| add (CLI verb) | run or install | v2 grammar |
+| popular, install count | starred, stars | Installs never rank or trust |
+| verified safe, secure, scanned | name the exact check | An attestation cannot guarantee safety |
+| people (audience) | devs | Brand guidelines |
+| Community (proper noun) | curators, `/community` route | Unglossed; the route stays |
+| named, naming (user copy) | talked about, mentioned | Internal word for the social route |
+| AI-powered | (cut) | skilld is not an AI product |
+
+## Open questions
+
+Naming calls this file does not settle. Resolve one, fold the answer in, delete the entry.
+
+1. **`Skill` or `skill` in site UI?**
+   The CLI glossary and new v3 copy use `Skill`. Most existing site UI, brand-guidelines.md, and meta descriptions use lowercase `skill`.
+   - Recase the site to `Skill`, one sweep, touches hundreds of strings.
+   - Keep lowercase on the site, record the split as deliberate.
+2. **`repo` or `repository` in site UI?**
+   The CLI glossary bans `repo`. The site uses `repo` in labels, props, and routes (`/gh/owner/repo`).
+   - Ban in new prose only, keep identifiers and routes.

app/components/community/_CommunityCreator.vue

@@ -119,7 +119,7 @@ function formatStars(stars: number): string {
       >
         <span class="flex items-center justify-between gap-4">
           <span class="font-mono text-sm uppercase tracking-widest text-muted">
-            Most popular skill
+            Most starred skill
           </span>
           <UIcon
             name="i-lucide-arrow-up-right"

app/pages/@[login]/index.vue

@@ -198,7 +198,7 @@ defineOgImage('Curator.takumi', {
   collectionCount: () => collections.value.length,
   skillCount: () => skills.value.length,
   skills: () => skills.value.slice(0, 4).map(skill => skill.display_name || skill.name),
-}, { alt: () => `${displayName.value} Community profile on skilld` })
+}, { alt: () => `${displayName.value} curator profile on skilld` })
 </script>
 
 <template>
@@ -573,7 +573,7 @@ defineOgImage('Curator.takumi', {
         <UButton
           v-else
           to="/community"
-          label="Browse Community"
+          label="Browse curators"
           icon="i-lucide-arrow-right"
           trailing
           color="neutral"

app/pages/collections/new.vue

@@ -4,7 +4,7 @@ const { isAuthenticated, user, loginUrl } = useAuth()
 
 useSeoMeta({
   title: 'New Collection',
-  description: 'Bundle the skills you reach for into a named collection.',
+  description: 'Bundle the skills you reach for into a collection.',
   robots: 'noindex',
 })
 

app/pages/index.vue

@@ -245,6 +245,13 @@ const installCommand = computed(() => {
     : ''
 })
 
+/**
+ * The authoring story runs a skilld-maintained Skill. The CLI itself never
+ * drafts a Skill, so the band hands the visitor the same run command every
+ * other surface prints.
+ */
+const authoringRunCommand = skillRunCmd('skilld-dev', 'skilld', 'generate-package-skill')
+
 const installTarget = computed<InstallTarget | null>(() => {
   const collection = leadCollection.value
   return collection
@@ -412,7 +419,7 @@ function recentUpdateDescription(item: RecentUpdateCard): string {
               Collections for better agent work.
             </h2>
             <p class="mt-4 max-w-xl text-base leading-relaxed text-muted text-pretty">
-              Shared by devs in the skilld community, covering discovery, planning, and review.
+              Shared by devs on X and Bluesky, covering discovery, planning, and review.
             </p>
             <p v-if="featuredCollections.length" class="data-label mt-3">
               {{ featuredCollections.length }} {{ featuredCollections.length === 1 ? 'collection' : 'collections' }} · {{ featuredSkillTotal }} {{ featuredSkillTotal === 1 ? 'skill' : 'skills' }}
@@ -671,7 +678,7 @@ function recentUpdateDescription(item: RecentUpdateCard): string {
         <div class="home-featured-heading">
           <div class="min-w-0">
             <h2 id="community-heading" class="home-featured-title text-balance">
-              Curators you can follow.
+              Curators you can watch.
             </h2>
             <p class="mt-4 max-w-xl text-base leading-relaxed text-muted text-pretty">
               <template v-if="communityTotal">
@@ -1041,16 +1048,24 @@ function recentUpdateDescription(item: RecentUpdateCard): string {
         <div class="home-publish-panel">
           <div>
             <h2 id="publish-heading" class="home-section-title home-publish-title text-balance">
-              Got a setup you keep reusing?
+              Author a Skill you own
             </h2>
             <p class="home-publish-summary mt-4">
-              skilld author starts a draft. You edit, own, and publish it in your repository, or bundle skills into a collection.
+              Run the skilld-maintained generate-package-skill Skill to draft a Skill for a package you maintain. Edit it, commit it to your repository, and skilld lists it with your name.
+            </p>
+            <p class="mt-4 text-sm">
+              <InstallCommand
+                id="publish-run-command"
+                :command="authoringRunCommand"
+                wrap
+                tabindex="0"
+              />
             </p>
           </div>
           <div class="home-publish-actions">
             <UButton
               to="/learn/author-npm-package-skills"
-              label="Bootstrap a package draft"
+              label="Read the authoring guide"
               color="neutral"
               variant="outline"
               trailing-icon="i-lucide-arrow-right"

layers/identity/app/pages/me/index.vue

@@ -143,7 +143,7 @@ onMounted(() => {
   if (route.query.welcome === '1') {
     toast.add({
       title: 'You\'re all set',
-      description: 'We\'ll let you know when watched repos update.',
+      description: 'Watched repos send a digest when they change.',
       color: 'success',
       icon: 'i-lucide-check-circle',
     })
@@ -399,15 +399,15 @@ function fmtDate(ts: number | null | undefined): string {
             {{ watchedRepositoryCount }} {{ watchedRepositoryCount === 1 ? 'repository supports' : 'repositories support' }} your skill updates.
           </p>
           <p class="mt-2 text-xs leading-relaxed text-muted">
-            Last GitHub sync: {{ fmtDate(me?.stars_synced_at) }}
+            Last GitHub import: {{ fmtDate(me?.stars_synced_at) }}
           </p>
           <UButton
             :loading="syncMutation.pending.value"
             class="mt-4 min-h-11"
             color="neutral"
             variant="outline"
             icon="i-lucide-refresh-cw"
-            label="Sync GitHub stars"
+            label="Import stars again"
             @click="sync"
           />
 

layers/identity/app/pages/onboarding/discover.vue

@@ -119,14 +119,14 @@ useSeoMeta({ title: 'Discover skills', robots: 'noindex' })
         color="neutral"
         variant="outline"
         icon="i-lucide-refresh-cw"
-        :label="data?.syncedAt ? 'Re-sync stars' : 'Sync stars'"
+        :label="data?.syncedAt ? 'Import stars again' : 'Import stars'"
         @click="syncStars"
       />
       <span v-if="syncing && syncProgress" class="text-xs text-muted">
         Page {{ syncProgress.page || '…' }} · {{ syncProgress.total }} repos cached · {{ syncProgress.matched }} match the registry
       </span>
       <span v-else-if="data?.syncedAt" class="text-xs text-muted">
-        Last synced {{ new Date(data.syncedAt * 1000).toLocaleString() }}
+        Last GitHub import {{ new Date(data.syncedAt * 1000).toLocaleString() }}
       </span>
     </div>
 
@@ -139,7 +139,7 @@ useSeoMeta({ title: 'Discover skills', robots: 'noindex' })
     </div>
     <div v-else-if="!skillItems.length" class="mt-6 rounded-lg border border-default p-6 text-sm text-muted">
       <template v-if="!data?.syncedAt">
-        We haven't checked your stars yet. Click <strong>Sync stars</strong> above, or
+        No star import yet. Click <strong>Import stars</strong> above, or
       </template>
       <template v-else>
         None of your starred repos with "skill" in the name are in the registry yet.

layers/marketing/app/components/FrameworkSkillsDirectory.vue

@@ -232,7 +232,7 @@ function showMore() {
         </section>
 
         <p class="mt-8 text-xs text-muted">
-          Synced {{ syncedAgo }}
+          Checked GitHub {{ syncedAgo }}
         </p>
       </template>
     </div>

layers/marketing/app/pages/skills/[cluster].vue

@@ -309,7 +309,7 @@ defineOgImage('Page.takumi', {
             Browse the rest.
           </h2>
           <p class="mt-3 max-w-2xl text-base leading-relaxed text-muted">
-            These all target the same kind of work. We show install counts for context.
+            These all target the same kind of work.
           </p>
         </div>
         <p class="data-label">

layers/marketing/app/pages/skills/best.vue

@@ -30,7 +30,7 @@ const ownerCount = computed(() => new Set(skills.value.map(s => s.owner)).size)
 // admission, resolves to a readable SKILL.md in its author's repo, and holds
 // official or trusted-curator standing. The page leads with those criteria
 // rather than asserting a ranking and hoping.
-const title = 'Best Agent Skills, Reviewed and Ranked'
+const title = 'Skills worth installing, reviewed'
 const description = computed(() =>
   `${total.value} agent skills that passed review, one per author, each from a maintainer you can name. Works with Claude Code, Cursor, and Codex. Read the SKILL.md in the author's own repo before you install.`,
 )

layers/marketing/app/pages/skills/trending.vue

@@ -240,7 +240,7 @@ const boardMeta = computed(() => {
   if (leaderboard.value) {
     const parts = [`${board.value.length} of ${leaderboard.value.total} reviewed repos`]
     if (starsSyncedOn.value)
-      parts.push(`stars synced ${starsSyncedOn.value}`)
+      parts.push(`stars checked ${starsSyncedOn.value}`)
     return parts.join(' · ')
   }
   const parts = [`${board.value.length} skills`]