Document scoped facet identity in docs, update collection terminology to scope, and mark all tasks complete

Author: eXamadeus

docs/cli/add.md

@@ -44,6 +44,7 @@ The manifest, lockfile, and receipt are **never written ahead** of success. On f
 | Registry name with version        | `viper-plans@1.2.3`                              | Exact pin.                                             |
 | Registry name with `@latest`      | `viper-plans@latest`                             | Re-resolves to the newest published version; `latest` is preserved verbatim in `facets.json` (the entry floats). Only a bare name pins. |
 | Registry name with wildcard       | `viper-plans@*`, `1.*`, `1.2.*`                  | Wildcard preserved in `facets.json`; resolved exact version goes in the lockfile. |
+| Scoped registry name              | `@scope/name`, `@scope/name@1.2.3`, `@scope/name@latest`, `@scope/name@1.*` | A scoped facet (`@scope/name`). The leading `@` marks the scope; a trailing `@` separates the version (so `@scope/name@1.2.3` pins `@scope/name` to `1.2.3`). Versioning and pinning rules are identical to unscoped names. |
 | GitHub shorthand                  | `github:owner/repo`, `github:owner/repo#main`    | Optional `#ref` (branch, tag, SHA).                    |
 | HTTPS git URL                     | `https://github.com/owner/repo.git#v1.0.0`       | Must end in `.git`.                                    |
 | SCP-style git URL                 | `git@github.com:owner/repo.git#main`             | Standard `user@host:path` SSH form.                    |
@@ -73,6 +74,10 @@ facet add viper-plans@1.2.3
 # specific resolved version.
 facet add viper-plans@1.*
 
+# Scoped facet  -- the leading @ is the scope; an optional trailing
+# @version pins it (e.g. @acme/deploy-tools@1.2.3).
+facet add @acme/deploy-tools
+
 # GitHub shorthand with a ref.
 facet add github:agent-facets/viper-plans#main
 

docs/cli/authoring/build.md

@@ -26,6 +26,8 @@ On success, the build writes output to `dist/`:
 
 - `dist/<name>-<version>.facet`  -- a self-contained archive (uncompressed tar containing `build-manifest.json` and `archive.tar.gz`)
 
+For a scoped facet identity, the name's `/` renders as a nested path under `dist/`. For example, `@acme/cowsay` at `1.0.0` is written to `dist/@acme/cowsay-1.0.0.facet`; the build creates the required parent directories.
+
 The `.facet` file is the single distributable artifact. The build manifest is embedded inside it. Use `--emit-manifest` to also write a loose copy of `build-manifest.json` to `dist/` for debugging or tooling integration.
 
 If the build fails, errors are displayed inline under the failed pipeline stage, with a suggestion to run `facet edit` to fix the issues.

docs/cli/authoring/create.md

@@ -15,10 +15,10 @@ If a `facet.json` already exists in the target directory, the command prompts fo
 
 ## Wizard flow
 
-1. **Name**  -- the facet name, in kebab-case (e.g., `my-facet`).
+1. **Name**  -- the facet identity. Either an unscoped name (`my-facet`) or a scoped name (`@scope/name`, e.g. `@acme/my-facet`). Each segment is kebab-case (a lowercase letter, then lowercase letters, digits, or hyphens).
 2. **Description**  -- a brief description of the facet.
 3. **Version**  -- defaults to `0.0.0`.
-4. **Assets**  -- add skills, agents, and commands by name. At least one asset is required. Each asset shows its description below the name  -- press Enter to edit the name, or press ↓ during name editing to edit the description in your terminal editor.
+4. **Assets**  -- add skills, agents, and commands by name. Asset names are always plain kebab-case local identifiers (`code-review`)  -- they are never scoped, even when the facet identity is. The first asset of each type defaults its name to the facet's unscoped name segment (`@acme/cowsay` suggests `cowsay`). At least one asset is required. Each asset shows its description below the name  -- press Enter to edit the name, or press ↓ during name editing to edit the description in your terminal editor.
 5. **Confirmation**  -- review the summary and confirm.
 
 ## Generated files

docs/guides/create-your-first-facet.md

@@ -17,10 +17,10 @@ facet create my-facet
 
 The [`facet create`](/cli/authoring/create) wizard walks you through four prompts:
 
-1. **Name** -- kebab-case identifier for the facet (e.g., `my-facet`).
+1. **Name** -- the facet identity: an unscoped name (`my-facet`) or a scoped name (`@scope/name`, e.g. `@acme/my-facet`). Each segment is kebab-case.
 2. **Description** -- a brief summary of what the facet does.
 3. **Version** -- defaults to `0.0.0`.
-4. **Assets** -- add skills, agents, and commands by name. At least one asset is required.
+4. **Assets** -- add skills, agents, and commands by name. Asset names are always plain kebab-case  -- never scoped, even when the facet identity is. At least one asset is required.
 
 After confirming, the wizard writes the project files.
 </Step>
@@ -189,6 +189,8 @@ dist/
 └── my-facet-0.0.0.facet
 ```
 
+A scoped facet identity renders as a nested path: `@acme/my-facet` at `0.0.0` is written to `dist/@acme/my-facet-0.0.0.facet`.
+
 The `.facet` file is the single distributable artifact. Use `--emit-manifest` to also write a loose `build-manifest.json` to `dist/` for debugging:
 
 ```sh

docs/guides/install-facets.md

@@ -15,11 +15,11 @@ facet adapter install
 
 Without a specifier, [`facet adapter install`](/cli/adapters/install) launches an interactive picker listing the first-party adapters:
 
-| Name          | Package                              | Tool        |
-| ------------- | ------------------------------------ | ----------- |
-| `opencode`    | `@agent-facets/adapter-opencode`     | OpenCode    |
-| `claude-code` | `@agent-facets/adapter-claude-code`  | Claude Code |
-| `codex`       | `@agent-facets/adapter-codex`        | Codex       |
+| Name          | Package                             | Tool        |
+|---------------|-------------------------------------|-------------|
+| `opencode`    | `@agent-facets/adapter-opencode`    | OpenCode    |
+| `claude-code` | `@agent-facets/adapter-claude-code` | Claude Code |
+| `codex`       | `@agent-facets/adapter-codex`       | Codex       |
 
 You can also install by name directly:
 
@@ -31,7 +31,7 @@ The adapter is downloaded, bundled into a self-contained `adapter.js`, and place
 
 ## Search the registry
 
-```sh
+```shell
 facet search <term>
 ```
 
@@ -59,14 +59,15 @@ facet add <source>
 
 ### Source grammar
 
-| Form                         | Example                                       |
-| ---------------------------- | --------------------------------------------- |
-| Registry name                | `facet add viper-plans`                        |
-| Registry name with version   | `facet add viper-plans@1.2.3`                  |
-| Major-pinned wildcard        | `facet add viper-plans@1.*`                    |
-| GitHub shorthand             | `facet add github:owner/repo#main`             |
-| HTTPS git URL                | `facet add https://github.com/owner/repo.git`  |
-| Local path                   | `facet add ./local-facets/my-plans`            |
+| Form                       | Example                                       |
+|----------------------------|-----------------------------------------------|
+| Registry name              | `facet add viper-plans`                       |
+| Registry name with version | `facet add viper-plans@1.2.3`                 |
+| Major-pinned wildcard      | `facet add viper-plans@1.*`                   |
+| Scoped registry name       | `facet add @acme/deploy-tools`                |
+| GitHub shorthand           | `facet add github:owner/repo#main`            |
+| HTTPS git URL              | `facet add https://github.com/owner/repo.git` |
+| Local path                 | `facet add ./local-facets/my-plans`           |
 
 A bare name (no version) resolves to the latest published version and writes the exact resolved version back to `facets.json`. Wildcards like `1.*` are preserved in `facets.json`; the specific resolved version goes in the lockfile.
 
@@ -90,12 +91,13 @@ The project manifest. Maps facet names to source specifiers:
 {
   "facets": {
     "viper-plans": "1.2.3",
-    "rezi": "0.5.0"
+    "rezi": "0.5.0",
+    "@acme/deploy-tools": "2.0.0"
   }
 }
 ```
 
-This is the source of truth for which facets belong to the project and at what version.
+This is the source of truth for which facets belong to the project and at what version. Scoped facets (`@scope/name`) appear as keys verbatim, including the leading `@`.
 
 ### `facets.lock`
 

docs/guides/publish-a-facet.md

@@ -57,7 +57,7 @@ Build your facet before publishing. If you have not built yet, or if your source
 facet build
 ```
 
-See [`facet build`](/cli/authoring/build) for details on the 6-stage pipeline. The build writes `dist/<name>-<version>.facet`.
+See [`facet build`](/cli/authoring/build) for details on the 6-stage pipeline. The build writes `dist/<name>-<version>.facet` (a scoped name renders as a nested path, e.g. `dist/@acme/cowsay-1.0.0.facet`).
 
 ## Publish
 

docs/specification/manifest.md

@@ -57,12 +57,12 @@ Authoring a facet with either section today produces a manifest the installer wi
 
 | Field         | Required | Type   | Description                   |
 | ------------- | -------- | ------ | ----------------------------- |
-| `name`        | Yes      | string | Facet name. MUST be non-empty.|
+| `name`        | Yes      | string | Facet identity. An unscoped name (`cowsay`) or a scoped name (`@scope/name`). See [Schema Constraints](#schema-constraints). |
 | `version`     | Yes      | string | Semver version string.        |
 | `description` | No       | string | Human-readable description.   |
 | `author`      | No       | string | Author name or identifier.    |
 
-The `name` and `version` fields MUST be present. A manifest missing either field MUST be rejected.
+The `name` and `version` fields MUST be present. A manifest missing either field MUST be rejected. The `name` MUST be a valid facet identity: an unscoped name, or a scoped `@scope/name`, where each segment is a lowercase kebab-case slug (starts with a lowercase letter; lowercase letters, digits, and hyphens after; ends with a letter or digit). Asset names (skills, agents, commands) are validated independently as local kebab-case identifiers and are never scoped.
 
 Consumers MUST tolerate unrecognized top-level fields. Unknown fields MUST be ignored  -- not rejected.