allye-pi 1.7.1 → 1.8.0

package/README.md

@@ -36,30 +36,28 @@ Your AI agent has **68+ tools** but no idea when to use them. Allye adds the met
 | **Skills** | Dynamic discovery | Agents find and follow your team's standards automatically — no manual config |
 | **Standards** | Guided creation | No team standards? Agent suggests creating them with your chosen scope |
 | **Boards** | Status progression | Correct transitions: backlog → todo → in_progress → review → done |
-| **Context** | Auto-loaded profile | User context, team info, and preferences injected before first message |
+| **Context** | On-demand profile | Agents load user context, team info, and preferences through the authenticated `allye` MCP tools |
 | **Language** | Multi-language | Agent responds in your language — configs are English, conversations are yours |
 
 ---
 
 ## Installation
 
-### Unified installer (all agents)
+### Repository installer boundary
 
-The fastest path if you have a terminal — one script detects every supported agent on your machine and configures each by the path it actually uses (MCP for agents that fetch it, skills-on-disk for agents that read them from a directory):
+The repository includes config-shape adapters and distribution verification, but
+shared runtime writes are currently fail-closed unless an API-backed ownership
+operation authorizes them. Physical uninstall is also blocked. Use the native
+platform procedures below; `./install.sh status` is safe for local inspection.
 
 ```bash
 git clone https://github.com/allye-app/allye-plugin.git
 cd allye-plugin
-./install.sh          # every detected agent
-./install.sh status   # what is installed, and at which version
-./install.sh install hermes
-./install.sh install pi
-./install.sh uninstall hermes
+./install.sh status
 ```
 
-Every write is additive and idempotent — your own MCP servers, plugins, and settings in each agent's config survive untouched. See [`docs/install-hermes.md`](docs/install-hermes.md) for Hermes Agent specifically (its OAuth step needs a terminal either way).
-
-Prefer the paste-into-agent or marketplace routes below? They still work — the unified installer doesn't replace them for Claude Code, OpenCode, Cursor, Codex, or Gemini CLI.
+A blocked `./install.sh install ...` or `./install.sh uninstall ...` result means
+no shared configuration was changed. It is not installation or cleanup success.
 
 ### Claude Code
 
@@ -73,7 +71,7 @@ Prefer the paste-into-agent or marketplace routes below? They still work — the
 **Step 2 — Authenticate:**
 1. Run `/plugin` to open the plugin panel
 2. Find **Allye MCP Server** and click **Connect**
-3. Your browser opens for OAuth login — sign in with your Allye account, select a team, and approve
+3. Your browser opens for OAuth login — sign in with your Allye account, select a tenant, and approve
 4. Done! The MCP server connects automatically
 
 > Authentication is handled via OAuth 2.1 — your browser opens once, and tokens are cached automatically.
@@ -85,19 +83,12 @@ After installing, you get:
 - **17 composable skills** — discovery, planning, execution, review, delivery, memory, verification, and delegation playbooks loaded as needed; no universal phase chain is required
 - **Parallel delivery, when a runtime is detected** — the Orchestrator can drive several independent stories at once, each in its own git worktree and its own watchable agent process; without a detected runtime, delivery degrades to the existing manual and automatic-subagent modes
 
-#### Multiple Allye accounts (multi-tenant)
-
-If you use different Allye accounts in different projects (e.g., personal account in `~/dev/myproject` and work account in `~/dev/company`), install the plugin with the **"local" scope** (per-project). Each project directory automatically gets its own OAuth session — no extra configuration needed.
-
-1. Open Claude Code in each project directory
-2. Install with local scope: `/plugin install allye` (select "local" when prompted)
-3. Run `/reload-plugins`
-4. Go to `/plugin` → **Connect** on the Allye MCP Server
-5. Log in with the Allye account you want for that project
-
-The plugin automatically generates a unique identifier per project directory, so each project authenticates independently. You can use a different Allye account in each project without conflicts.
+#### Tenant selection
 
-> **Single account users don't need this.** If you only use one Allye account, just install and authenticate — it works out of the box.
+Every project uses the same `allye` server URL:
+`https://mcp.allye.app/mcp`. Choose the tenant during OAuth consent. Separate
+authorizations create independent grants without encoding a tenant or account in
+the URL.
 
 **To update:** `/plugin update allye` then `/reload-plugins`
 
@@ -147,7 +138,7 @@ Install allye-plugin following: https://raw.githubusercontent.com/allye-app/ally
 ```
 
 After installing:
-- **MCP server** configured in `~/.codex/config.toml`
+- **`allye` MCP server** at `https://mcp.allye.app/mcp`, authenticated by Codex's native OAuth flow
 - **`AGENTS.md`** installed with workflow instructions
 
 **To update:** Paste this into your agent:
@@ -175,54 +166,25 @@ Update allye-plugin following: https://raw.githubusercontent.com/allye-app/allye
 ### Pi
 
 Pi uses the published native package `allye-pi`, while keeping
-`skills/*/SKILL.md` as the only canonical skill source. The installer delegates
-installation to Pi's official package manager and does not edit Pi's
-`settings.json` or MCP configuration:
-
-```bash
-./install.sh install pi       # production: npm:allye-pi
-./install.sh uninstall pi     # removes npm:allye-pi
-```
-
-Other official Pi sources are available when you choose them explicitly:
+`skills/*/SKILL.md` as the only canonical skill source. Install through Pi's
+package manager:
 
 ```bash
 pi install npm:allye-pi
-pi install git:github.com/allye-app/allye-plugin
-ALLYE_PI_INSTALL_SOURCE=local ./install.sh install pi  # checkout development only
 ```
 
-The installer defaults to npm. Use the Git command for a tagged repository
-checkout, and the `local` opt-in only while developing this repository. See
-[`docs/install-pi.md`](docs/install-pi.md) for MCP setup, mode selection, and
-Herdr integration.
+Configure one `allye` server at `https://mcp.allye.app/mcp` in the effective
+pi-mcp-adapter source, then run `/mcp-auth allye` and `/mcp reconnect allye`.
+The package and repository installer do not edit Pi's MCP configuration. See
+[`docs/install-pi.md`](docs/install-pi.md) for source selection, authentication,
+and the installer boundary.
 
 ### Hermes Agent
 
-```bash
-git clone https://github.com/allye-app/allye-plugin.git
-cd allye-plugin
-./install.sh install hermes
-```
-
-After installing:
-- **MCP server** configured in `~/.hermes/config.yaml` (OAuth needs a terminal — see [`docs/install-hermes.md`](docs/install-hermes.md))
-- **16 skills** exported to `~/.hermes/skills/allye/` — Hermes reads skills from disk, not over MCP
-- **`allye-bootstrap` plugin** installed and enabled — injects `using-allye` at session start
-
-**To update:** `cd allye-plugin && git pull && ./install.sh install hermes`
-
-### Manual (all agents)
-
-```bash
-git clone https://github.com/allye-app/allye-plugin.git
-cd allye-plugin
-./install.sh
-```
-
-Auto-detects every installed agent and configures each one — MCP for agents that fetch skills over it, skills-on-disk for Hermes.
-
-**To update:** `cd allye-plugin && git pull && ./install.sh`
+Follow [`docs/install-hermes.md`](docs/install-hermes.md) for its native package
+and OAuth procedure. The repository installer preserves its fail-closed
+ownership boundary and must not be described as a general-purpose config writer
+or cleanup command.
 
 ---
 
@@ -245,13 +207,10 @@ Paste this into your agent's chat:
 | Cursor | `Update allye-plugin following: https://raw.githubusercontent.com/allye-app/allye-plugin/main/docs/update-cursor.md` |
 | Codex | `Update allye-plugin following: https://raw.githubusercontent.com/allye-app/allye-plugin/main/docs/update-codex.md` |
 | Gemini CLI | `Update allye-plugin following: https://raw.githubusercontent.com/allye-app/allye-plugin/main/docs/update-gemini.md` |
-| Hermes Agent | see [`docs/update-hermes.md`](docs/update-hermes.md) — run `./install.sh install hermes` after `git pull` |
+| Hermes Agent | see [`docs/update-hermes.md`](docs/update-hermes.md) for the native update procedure |
 
-### Manual
-
-```bash
-cd allye-plugin && git pull && ./install.sh
-```
+The repository's `install.sh` remains an inspection and API-authorized
+distribution boundary; it does not replace these native updates.
 
 ---
 
@@ -269,7 +228,7 @@ Every phase, on every platform:
 - Responds in **your language** (detected from your messages, falling back to your profile only before you've said anything)
 - Calls `initialize` to load your profile and team context
 - **Discovers team skills** before starting — coding standards, templates, checklists
-- If no standards found → **suggests creating them** with your chosen scope (personal/team/organization). Marketplace is a legacy read-only browsing/source surface, never a write destination.
+- If no standards found → **suggests creating them** with your chosen scope (personal/team/organization). The internal library is the only Skills source.
 - Searches memories for past decisions and session state
 - Saves session state before ending
 
@@ -310,7 +269,7 @@ Once an epic's whole status cascade completes, the Orchestrator offers — never
 
 ## Skills
 
-Skills are the knowledge base that powers the agents. 16 workflow skills are published in the **Allye marketplace** — available to all users without setup (`setup` itself is Claude Code's local install-time skill and isn't marketplace-published).
+Skills are the internal knowledge base that powers the agents. Workflow skills ship with the installed package and are available through the internal Skills library.
 
 | Skill | What it teaches |
 |-------|----------------|

package/docs/install-pi.md

@@ -1,7 +1,11 @@
 # Install Allye for Pi
 
-The Pi adapter is a thin native Pi package. It does not copy workflow skills or
-replace Pi's MCP configuration:
+The Pi adapter is a thin native Pi package. Installation/configuration is not
+API authorization, release approval, publication, or distribution success. Official
+distribution consumes only the API-authorized immutable release identity
+(`skill_id`, `release_id`, `version`, canonical SHA-256 hash, and supplied origin); a revoked or
+otherwise ineligible release remains blocked until the API returns matching physical
+runtime evidence. It does not copy workflow skills or replace Pi's MCP configuration:
 
 - `skills/*/SKILL.md` in this repository remains the canonical skill source;
 - the adapter exposes that directory through Pi's `resources_discover` event;
@@ -9,70 +13,74 @@ replace Pi's MCP configuration:
   MCP server via `pi-mcp-adapter`;
 - Herdr is exposed as an optional capability when the Pi session provides `HERDR_ENV=1`.
 
-## Official package sources
+## Package sources and installer boundary
 
-### npm (default production install)
+Install the production package through Pi's native package manager:
 
 ```text
-./install.sh install pi
-# equivalent to:
 pi install npm:allye-pi
-
-./install.sh uninstall pi
-# equivalent to:
-pi remove npm:allye-pi
 ```
 
-The installer delegates installation and persistence to Pi's official package
-manager. It never edits `~/.pi/agent/settings.json` manually and the default
-source is always the published npm package. Restart Pi (or run `/reload`) after
-installation.
+Use Git only when the repository source is intentional, preferably at a tag:
 
-### Git
+```text
+pi install git:github.com/allye-app/allye-plugin
+```
 
-Use Git when you want Pi to install the repository package directly, preferably
-at a tag for reproducibility:
+For development against a local checkout:
 
 ```text
-pi install git:github.com/allye-app/allye-plugin
-pi remove git:github.com/allye-app/allye-plugin
+pi install /absolute/path/to/allye-plugin
 ```
 
-This is separate from `./install.sh install pi`, which intentionally remains an
-npm install.
+Pi owns package persistence and runtime dependencies. Removing the package with
+`pi remove <the-exact-source>` is a separate, intentional operation; it does not
+remove MCP configuration or OAuth credentials.
+
+The repository's `./install.sh install pi` path is fail-closed for shared
+runtime configuration unless an API-backed ownership operation authorizes it,
+and `./install.sh uninstall pi` does not perform physical removal. Use
+`./install.sh status` for inspection; do not describe a blocked installer result
+as installation or cleanup success.
+
+## Configure the canonical MCP server
+
+The package never edits Pi's MCP files. Use the effective source displayed by
+`/mcp`: project `.mcp.json` or `.pi/mcp.json`,
+`~/.config/mcp/mcp.json`, `~/.agents/mcp.json`,
+`~/.agents/mcp/mcp.json`, `~/.pi/agent/mcp.json`, or
+`$PI_CODING_AGENT_DIR/mcp.json` when that override is set.
+
+Define exactly one server named `allye`:
+
+```json
+{
+  "allye": {
+    "type": "http",
+    "url": "https://mcp.allye.app/mcp"
+  }
+}
+```
 
-### Local checkout (development only)
+The effective pi-mcp-adapter source may wrap entries under `mcpServers`; preserve
+its existing shape and every unrelated server. Do not add authorization headers
+or fixed OAuth client metadata.
 
-A checkout path is supported, but only through an explicit opt-in so a normal
-production install cannot accidentally load uncommitted code:
+Authenticate and connect through the adapter:
 
 ```text
-cd /path/to/allye-plugin
-ALLYE_PI_INSTALL_SOURCE=local ./install.sh install pi
-ALLYE_PI_INSTALL_SOURCE=local ./install.sh uninstall pi
+/mcp-auth allye
+/mcp reconnect allye
 ```
 
-That delegates to `pi install /absolute/path/to/allye-plugin` and
-`pi remove /absolute/path/to/allye-plugin`. Pi manages the package settings and
-runtime dependencies in every case; `skills/*/SKILL.md` remains the single
-canonical skill tree.
-
-The installer deliberately does **not** edit any MCP file. Relative project
-paths are resolved from the installer `PWD`, or from `ALLYE_PI_PROJECT_DIR` when
-installing for a different project. Configure Allye in
-one of the sources supported by `pi-mcp-adapter`: project `.mcp.json` or
-`.pi/mcp.json`, `~/.config/mcp/mcp.json`, `~/.agents/mcp.json`, `~/.agents/mcp/mcp.json`, or
-`~/.pi/agent/mcp.json` (or `$PI_CODING_AGENT_DIR/mcp.json` when that Pi
-override is set). For example, use an
-`allye` server pointing to `https://mcp.allye.app/mcp/<tenant-slug>`.
-Authenticate with `/mcp-auth allye` when required. Existing MCP servers are
-preserved. `./install.sh install pi` reports the first supported source that
-already contains Allye and warns only when none does.
+Use `/reload` after changing the effective config. `/mcp logout allye` clears
+only Allye's native credential when an intentional reconnection is needed; it
+does not edit or remove the server entry.
 
 Both npm and Git packages use the root Pi manifest and let Pi install
 `pi-mcp-adapter` as a runtime dependency. The npm tarball contains the adapter
 source, canonical `skills/` directory, and Pi documentation; it is not the full
-plugin checkout and is not the installer input.
+plugin checkout and is not an installer input.
 
 ## Adaptive toolkit
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "allye-pi",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "description": "Pi package adapter for the canonical Allye workflow",
   "type": "module",
   "keywords": [
@@ -39,7 +39,8 @@
   "scripts": {
     "typecheck": "tsc --noEmit -p packages/allye-pi/tsconfig.json",
     "test:pi": "node --experimental-strip-types --test packages/allye-pi/src/index.test.ts",
-    "test:installer": "bash install/test-pi.sh"
+    "test:adapters": "node --experimental-strip-types --test packages/allye-pi/src/runtime-adapters.test.ts",
+    "test:installer": "bash install/test-validation.sh && bash install/test-pi.sh && bash install/test-installer.sh && bash install/test-multi-runtime-distribution.sh && bash install/test-pi-distribution-http.sh && bash install/test-claude-distribution.sh"
   },
   "repository": {
     "type": "git",

package/skills/setup/SKILL.md

@@ -1,103 +1,103 @@
 ---
 name: setup
 description: First-time setup for the Allye plugin. Uses OAuth for ALL platforms — no PAT.
-version: "1.2"
+version: "1.3"
 category: bootstrap
 ---
 
 # Allye Setup
 
 <EXTREMELY_IMPORTANT>
-## Allye ALWAYS uses OAuth. Never ask for a PAT.
+## Allye MCP always uses native OAuth
 
-The setup flow depends on whether the platform supports native MCP OAuth:
-
-- **Claude Code / Claude Desktop** → OAuth is automatic via `.mcp.json`. No setup needed.
-- **All other platforms** (OpenCode, Cursor, Codex, Gemini, etc.) → Run the OAuth browser login script.
-
-**NEVER ask the user for a PAT. NEVER mention PAT as an option.**
+Configure one remote server named `allye` at `https://mcp.allye.app/mcp`. Let the
+host runtime perform discovery, dynamic client registration, authorization-code
+exchange, token storage, and refresh. Static bearer headers, PATs, fixed client
+IDs, tenant-specific URLs, and external login helpers are not part of setup.
 </EXTREMELY_IMPORTANT>
 
-## Step 1: Detect Platform
-
-Check which platform/agent is running. You can infer this from:
-- The environment (Claude Code has `CLAUDE_CODE` env, Claude Desktop has specific hooks)
-- The available tools and context
-- Or simply ask: "Which platform are you using?"
-
-## Step 2A: Claude Code / Claude Desktop (Native OAuth)
-
-If the user is on Claude Code or Claude Desktop:
+## Step 1: Detect the platform
 
-> **Allye is already configured!** The plugin's `.mcp.json` handles OAuth automatically.
->
-> The first time you use a Allye tool, your browser will open for login.
-> Just start using Allye — try asking me to search memories or list work items.
+Infer the current platform from the runtime when possible. Otherwise ask which
+supported agent the user wants to configure.
 
-**Stop here. No further setup needed.**
+## Step 2: Configure and authenticate one Allye entry
 
-## Step 2B: Other Platforms (OAuth via Browser Login Script)
+Preserve every unrelated server and credential. If an older Allye entry exists
+under another name, identify its effective config source, remove only that
+entry through the host's native management command, and keep only `allye`.
 
-For OpenCode, Cursor, Codex, Gemini, or any platform without native MCP OAuth:
+### Claude Code / Claude Desktop
 
-Tell the user:
+The plugin's `.mcp.json` already declares `allye`. Open the MCP or plugin panel,
+select **Allye**, and choose **Connect**. The browser completes consent.
 
-> I'll run the Allye OAuth login to connect your account via browser.
+For an intentional reconnect, use **Clear authentication** for Allye, then
+**Authenticate/Connect**. Do not sign out of the host account.
 
-### Run the OAuth login script:
+### Codex
 
 ```bash
-bash "${CLAUDE_PLUGIN_ROOT:-$(pwd)}/scripts/oauth-login.sh"
+codex mcp get allye >/dev/null 2>&1 \
+  || codex mcp add allye --url https://mcp.allye.app/mcp
+codex mcp login allye
 ```
 
-If `CLAUDE_PLUGIN_ROOT` is not set, find the script:
+If a legacy Allye entry has a different name, use `codex mcp logout <old-name>`
+and `codex mcp remove <old-name>` for that entry only before adding `allye`.
 
-```bash
-SCRIPT=$(find ~/.claude/plugins -name "oauth-login.sh" -path "*/allye*" 2>/dev/null | head -1) || SCRIPT=$(find . -name "oauth-login.sh" 2>/dev/null | head -1); echo "$SCRIPT"
+### OpenCode
+
+Its effective `opencode.json` must contain:
+
+```json
+{
+  "mcp": {
+    "allye": {
+      "type": "remote",
+      "url": "https://mcp.allye.app/mcp",
+      "enabled": true
+    }
+  }
+}
 ```
 
-Then run it:
+Preserve the rest of the file, then authenticate and confirm:
 
 ```bash
-bash "$SCRIPT"
+opencode mcp auth allye
+opencode mcp list
 ```
 
-The script will:
-1. Open the browser for Allye OAuth login
-2. Start a local callback server on port 9316
-3. After the user logs in and selects a team, capture the authorization code
-4. Exchange the code for tokens
-5. Output `ALLYE_ACCESS_TOKEN=...` and `ALLYE_REFRESH_TOKEN=...`
+### Pi with pi-mcp-adapter
 
-### Configure the platform with the obtained token:
+Use the effective MCP source shown by `/mcp` and define an `allye` remote server
+at the canonical URL. The Allye repository installer does not write Pi's MCP
+configuration.
 
-**For OpenCode:**
-The `opencode.json` manifest uses `${ALLYE_ACCESS_TOKEN}`. Set the env var:
+Authenticate and connect in Pi:
 
-```bash
-export ALLYE_ACCESS_TOKEN="<the token from the script>"
+```text
+/mcp-auth allye
+/mcp reconnect allye
 ```
 
-Or update `opencode.json` directly with the token.
+Use `/reload` after changing the effective config source. `/mcp logout allye`
+clears only Allye's native credential when the user explicitly requests a
+reconnection.
 
-**For Cursor:**
-Add MCP server in Cursor settings (Settings → MCP Servers):
-- Name: `allye-mcp`
-- URL: `https://mcp.allye.app/mcp`
-- Headers: `Authorization: Bearer <token>`
+### Other native MCP clients
 
-**For other platforms:**
-Configure the MCP connection with:
-- URL: `https://mcp.allye.app/mcp`
-- Authorization header: `Bearer <token>`
+Add a remote HTTP MCP server named `allye` at the canonical URL and use the
+client's native OAuth action. Preserve unrelated configuration and credentials.
 
-### Confirm setup:
+## Step 3: Confirm MCP access
 
-> **Allye connected via OAuth!**
->
-> Start a new session to activate the Allye tools.
+Start or reload the host session, confirm the `allye` server is connected, and
+invoke a read-only Allye tool. Tenant selection happens during consent; the URL
+never contains a tenant slug.
 
-## Step 3: Delivery configuration
+## Step 4: Delivery configuration
 
 Ask once, here, rather than at every dispatch. Five parallel stories would otherwise mean
 ten identical questions whose answer never varies.
@@ -210,16 +210,17 @@ Platform capability also constrains the map. OpenCode has six agent personas; Cu
 and Gemini CLI have one agent and no picker — routing a specific persona to them silently
 does nothing.
 
-## Token Refresh
+## Authentication lifecycle
 
-OAuth tokens expire. When a token expires:
-- **Claude Code/Desktop**: Automatic refresh via OAuth flow
-- **Other platforms**: Run the login script again: `bash scripts/oauth-login.sh`
+The host runtime rotates access and refresh tokens automatically. A normal
+restart, an HTTP 403 authorization result, or an HTTP 503 dependency failure
+does not require clearing credentials or opening the browser.
 
-## Error Handling
+An explicit grant revocation or the 90-day grant limit requires a new consent.
+When the user intentionally reconnects, clear only the `allye` entry:
 
-- `python3` not found → Required for the OAuth callback server. Install Python 3.
-- `openssl` not found → Required for PKCE. Install OpenSSL.
-- Browser doesn't open → Copy the URL from the terminal and open manually.
-- Port 9316 in use → Run with a different port: `bash scripts/oauth-login.sh 9317`
-- `jq` not found → `brew install jq` / `sudo apt install jq`
+- **Claude Code/Desktop:** Allye → **Clear authentication** → **Authenticate/Connect**
+- **Codex:** `codex mcp logout allye`, then `codex mcp login allye`
+- **OpenCode:** `opencode mcp logout allye`, then `opencode mcp auth allye`
+- **Pi:** `/mcp logout allye`, then `/mcp-auth allye` and `/mcp reconnect allye`
+- **Other clients:** use the host's clear/reconnect action scoped to `allye`

package/skills/tools-quickref/SKILL.md

@@ -192,18 +192,17 @@ Manage and export workflow skills.
 | `skill_get` | Get skill by ID | `skill_id`* or `id`* |
 | `skill_update` | Update a skill | `skill_id`* or `id`*, `skill_name`, `skill_content`, `skill_description`, `skill_category`, `skill_is_active` |
 | `skill_delete` | Delete a skill | `skill_id`* or `id`* |
-| `skill_marketplace` | Browse marketplace skills | `query`, `limit`, `offset` |
 | `skill_fork` | Fork a readable source skill into an independent internal draft | `skill_id`* or `id`*, `skill_scope`*, `skill_slug` (explicit namespace key; required to retry a collision), `skill_name`, `skill_category` (scope only `personal`/`team`/`organization` — no `marketplace`) |
 | `skill_export` | Export a skill in agent format | `skill_id`* or `id`*, `skill_export_format`* |
 | `skill_import_github` | Import skill from GitHub | `repo_url`* |
 | `skill_install` | Install a skill | `skill_id`* or `id`* |
 | `skill_export_merged` | Export multiple skills merged | `skill_ids`*, `skill_export_format`* |
 
-**`skill_create` requires all three of `skill_content`, `skill_scope`, and `skill_category`** — easy to miss since only `skill_name` reads as obviously required. Write scopes are only `personal`, `team`, and `organization`; `marketplace` is legacy read-only browsing/source material and must never be sent as a create, import, update, fork target, publication, or rating destination.
+**`skill_create` requires all three of `skill_content`, `skill_scope`, and `skill_category`** — easy to miss since only `skill_name` reads as obviously required. Write scopes are only `personal`, `team`, and `organization`. A retired public-scope request returns API error `MARKETPLACE_RETIRED` (HTTP 410): `Marketplace público foi aposentado; use a biblioteca interna de Skills.`
 
 For shared writes, the API is authoritative: the authenticated actor must be the container owner/admin, have tenant-scoped `skills:manage`, or hold an active maintainer grant. Membership gives read access, not write access. Team writes require the selected active team (`team_id`/request context); personal and organization writes do not. Use `skill_resolve` for canonical `team > organization > personal` resolution and honor its `candidates`, `selected`, `owner`, `rule`, `reason`, and `conflict` fields.
 
-Forks are independent drafts with `forked_from_id`, a new author, no copied grants, and preserved source provenance when available. If a fork returns `409 Conflict`, choose a different explicit `skill_slug` and retry; never silently suffix or overwrite a namespace. Marketplace can be browsed and used as readable source material for an internal fork, but it is never an internal write scope.
+Forks are independent drafts with `forked_from_id`, a new author, no copied grants, and preserved source provenance when available. If a fork returns `409 Conflict`, choose a different explicit `skill_slug` and retry; never silently suffix or overwrite a namespace. The internal library is the only Skills source.
 
 **Export formats:** `cursor`, `claude`, `copilot`, `windsurf`, `opencode`, `codex`, `gemini`
 **Skill scopes (create/import/fork):** `personal`, `team`, `organization` (never `marketplace`)