Changelog

​

Private facets in facet search results

​

Clearer terminology and errors

• Adapter compatibility errors say “adapter SDK API.” The diagnostics in facet adapter list, the failures that stop facet build, facet add, facet remove, and facet install, and the CLI’s built-in usage guidance all use one term for the adapter SDK API version an adapter declares.
• Git authentication failures name the real requirement. A clone that needs credentials now fails with private repositories require git authentication and suggests configuring git authentication or using a public URL. The old message claimed only public repos and SSH were supported, which is no longer true.

​

Agent Facets is in open beta

• Public publishing remains free.
• Personal private publishing is free during the beta.
• Private publishing for teams is a paid offering available by request.

​

Git-sourced installs no longer crash on a cold cache

• Only fresh clones were affected. A first install, or one whose cache slot was cold or evicted, hit the crash. Installs served from an audited cache hit, and facets from the registry or a local path, never took this path.
• Nothing about verification changed. The same entries are audited, and the cache records the complete set, including supplementary files that no asset owns.

​

New command: facet update

facet update                    # take every target the declared range permits
facet update --latest           # take the newest release, ignoring ranges
facet update --dry-run          # print the plan; change nothing
facet update --interactive      # choose per facet, and which version each takes

• Plain facet update respects your ranges. Every facet moves to the newest version its declared specifier already permits.
• --latest crosses the range, minimally. It rewrites the specifier by the smallest edit that admits the new version, preserving how you expressed intent: a pin stays a pin, 1.* becomes 2.*, and * and latest are left exactly as authored.
• --dry-run writes nothing. No manifest, no lockfile, no receipt, no assets, and no adapter installation, so it is safe on a machine with no adapter connected.
• --interactive picks per facet. Every row starts on its latest release with nothing selected; a facet you never touch is left alone.

​

Breaking: facet upgrade is no longer a placeholder

​

Version numbers are bounded by exact integer representation

​

Rollback no longer leaves empty directories behind

• An empty directory recreated at a managed path was left behind, even though nothing was inside it.
• A pre-existing directory that rollback emptied was never removed at all, because the run had not created it.

• A failed run leaves a tidy tree. Rollback walks up from each restored file and removes any directory it left empty, so you no longer have to delete hollow folders by hand.
• Only empty directories are ever removed. A directory holding anything at all — your files or the tool’s — is refused in a single atomic step. There is no window in which content can be lost.
• Cleanup is bounded. The walk never climbs past a tool’s configuration directory (such as .claude or .opencode). It can remove that directory only when the failed install created it.

​

OpenCode: MCP servers land where OpenCode actually reads them

1. .opencode/opencode.jsonc
2. .opencode/opencode.json
3. opencode.jsonc
4. opencode.json

1. the highest-precedence document that already defines an mcp member (an empty {} counts);
2. otherwise the highest-precedence document that exists;
3. otherwise .opencode/opencode.jsonc, created.

• A shadowed copy of a desired server is left alone. The target’s definition already wins, so deleting from a file this run is not otherwise writing is not the adapter’s call. Previously the losing copy was deleted.
• An obsolete owned entry is still removed from every document that defines it, so a removal cannot promote a shadowed copy and leave the server configured.

​

agent-facets@0.32.0 on npm

• agent-facets@0.32.0

​

Adapter API 0.3 end-to-end

• Byte-exact rollback. A failed run restores the exact prior bytes and permission bits. YAML front matter and TOML formatting come back as authored instead of being re-rendered from parsed data.
• No phantom drift. A file already holding the bytes a plan would write contributes no change, so a re-install touches no modification time.
• Contested files are preserved, not clobbered. A file this run wrote and something else then changed is reported by path, and rollback continues past it so one contested file cannot strand the rest.
• Failed runs report what they left on disk. The report distinguishes a file deliberately left alone from one whose restoration genuinely failed, and gives each its own remedy. No file is ever reported as both restored and unrecoverable.

​

Safer MCP configuration

​

facet adapter install is now facet adapter add

​

Breaking: reinstall every adapter

facet adapter list

​

Adapter SDK 0.30.0 with adapter API 0.3

• @agent-facets/adapter@0.30.0
• @agent-facets/adapter-claude-code@0.11.0
• @agent-facets/adapter-codex@0.9.0
• @agent-facets/adapter-opencode@0.12.0

​

Adapters plan, the CLI writes

• Byte-exact rollback. A failure restores the precise prior bytes and permission bits. Comments, member order, and TOML/YAML formatting come back exactly as authored — restoration no longer depends on re-rendering an asset from parsed data.
• No phantom drift. A file already holding the bytes a plan would write contributes no change, so a re-install touches no modification time.
• Inspected files stay untouched on rollback. A file the run only read is never journaled, so a concurrent edit to it survives a rollback.
• Preconditions are checked immediately before each write. A file something else moved between planning and writing is refused and reported, never clobbered.

​

Safer MCP configuration

​

For adapter authors

• installAsset / readAsset / deleteAsset are replaced by assets: false | { planInstall, planRemoval }.
• supportsInstall is gone — an adapter states its asset capability the same way it states MCP support.
• The MCP capability is mcpServers: false | { plan }. apply, the opaque plan type, and the conflict/document-changed reason are removed; concurrency is detected once, by the CLI.
• Every asset request carries projectRoot.

​

Coordinated with the next CLI release

​

agent-facets@0.31.0 on npm

• agent-facets@0.31.0
• @agent-facets/protocol@0.31.0
• @agent-facets/adapter@0.29.0
• @agent-facets/adapter-claude-code@0.10.0
• @agent-facets/adapter-codex@0.8.0
• @agent-facets/adapter-opencode@0.11.0

​

Hardening across the MCP stack

• Conflict reports name the exact key. Cross-facet collisions and MCP takeover prompts now identify each conflicting adapter key by name, so a report never leaves you guessing which entry a facet is claiming.
• Terminal output escapes control characters. Server names, commands, arguments, and environment values shown on the approval screen and in failure reports are escaped, so a hostile declaration cannot rewrite what your terminal renders.
• BOM and indentation preservation. Rewrites of .mcp.json, opencode.jsonc/opencode.json, and .codex/config.toml keep any existing byte-order mark and reuse the file’s own indentation, instead of forcing a reformat every time an entry is added or removed.
• opencode.jsonc comments stay where you put them. The JSONC rewriter preserves comment placement across a reconciliation, so a project-owned edit does not shuffle notes attached to unrelated settings.
• Install failures name the gate. When an install stops before writing, the failure block now names the specific gate that halted it (missing MCP approval, unsupported adapter API, collision, drift) rather than a generic message.

​

Facets can declare MCP servers

{
  "servers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    },
    "docs": { "type": "http", "url": "https://mcp.example.com/docs" }
  }
}

​

Approval before anything is configured

facet install --accept-mcp
facet add mcp-tools --accept-mcp
facet remove old-facet --accept-mcp

"mcp-tools": {
  "source": "1.*",
  "materialization": { "servers": { "docs": { "kind": "omitted" } } }
}

​

Aliasing, omission, and collisions

​

Configuration is written, never run

​

Breaking: old server reference forms are rejected

​

Breaking: format versions

​

Rollout

​

agent-facets@0.30.0 on npm

​

Install receipt hardening

• Frozen install that cannot write the receipt. Under --frozen-lockfile, if facet install materializes every asset but the receipt write fails, the run still succeeds — the locked set it reproduced is intact — and it now says the assets it wrote are untracked, instead of reporting a clean success.
• Unusable receipt. A receipt that exists but cannot be used (unreadable, or recorded against a different project) is reported instead of being silently replaced by a lockfile projection. A single receipt entry that fails validation is reported the same way, and the files it covered are left in place.
• Removal-resolution report names the gate. When facet remove falls back from the offline fast-path to the ordinary pipeline (which needs the network), the failure now names which gate sent it down that path, so an error naming a facet you are keeping is not a mystery.
• Ctrl-C is honored during facet remove. Before anything is deleted, nothing is written; after deletion, the deletes are rolled back rather than committed.

​

facet instructions refresh

• Generated overview index. The default overview now opens with an index of every instruction topic. The index is generated from a single typed topic registry, so it cannot drift from the topics the command actually serves.
• Updated topic prompts. Topic content now covers README.md and supplementary-file authoring, single-segment asset naming and the shared skill/command namespace, and adapter API 0.1 compatibility recovery.

​

Two facets, one name

Installation is paused: two or more facets want the same name.
1 group · 1 still to resolve · nothing has been written yet

  project skills and commands — "planning"
    ✕ unresolved   viper-plans  skill planning
    ✕ unresolved   team-tools   skill planning

• Nothing is written until you decide. A collision leaves facets.json, facets.lock, the receipt, and your materialized assets byte-identical. Cancelling with Esc ends the command without applying anything — it reports the cancellation and exits non-zero, and your project is exactly as you left it.
• You decide once. Your choices are saved into facets.json, so the next install — and every teammate’s, and CI’s — replays them without prompting.
• No tool picks a winner. Not the CLI, not the registry, not the facet authors. A silent winner means a silently discarded asset.

​

Alias or omit any asset

"team-tools": {
  "source": "1.*",
  "materialization": {
    "skills": {
      "planning": { "kind": "aliased", "as": "team-planning" },
      "scratch": { "kind": "omitted" }
    }
  }
}

• Aliasing renames the file, nothing else. Archive paths, per-file integrity, and the lockfile all keep the publisher’s authored name. That is what makes an alias safe: it can never be used to smuggle different content in under a familiar name.
• Omitted assets are still verified. They are resolved, hashed, and recorded in the lockfile — they are just never written to disk. Dropping them from the lockfile would make an omission indistinguishable from a facet that never published the asset.
• Skills and commands share one namespace, agents have their own. A skill deploy and a command deploy collide; an agent deploy coexists with both.

​

Breaking: facets.json entries may be objects

{
  "manifestVersion": 0.1,
  "facets": {
    "cowsay": "1.*",
    "team-tools": { "source": "1.*", "materialization": { "skills": { "planning": { "kind": "aliased", "as": "team-planning" } } } }
  }
}

​

Breaking: lockfile 0.3 (and receipt 0.3)

{
  "scope": "project", "type": "skill", "name": "planning",
  "materialization": { "kind": "aliased", "as": "team-planning" },
  "files": [{ "path": "skills/planning/SKILL.md", "integrity": "sha256:…" }]
}

​

The install pipeline resolves everything before writing anything

• Disposition changes report as updated. Aliasing an asset at an unchanged version is a real change to what is on disk, not a no-op and not a repair.
• Stale choices are pruned and reported. If you upgrade a facet and the publisher removed an asset you had aliased, the override is dropped on a successful install and the CLI tells you which one.

​

Breaking: only your install receipt authorizes deletion

• Your project’s desired state authorizes writes. An install still materializes every declared asset, overwriting an unmanaged file that happens to occupy the same name. (If what is already there matches byte for byte, it is adopted without a rewrite.) Either way the file is tracked from then on.
• The receipt authorizes deletions. Files the CLI has no record of writing are never deleted.

• Pull a teammate’s facets.lock onto a machine that never ran an install, then facet remove the facet: facets.json and facets.lock drop it and the files stay exactly where they are. The summary says so instead of reporting a cleanup that did not happen, and those files are then yours to delete by hand.
• facet remove may need the network. The offline guarantee is a property of tracked state, not of removal. If a facet you are keeping is not fully accounted for by your receipt, the removal runs the ordinary pipeline to materialize it before claiming it — which succeeds when the content is reachable and fails, deleting nothing, when it is not. Run facet install first to take ownership.
• An unusable receipt is reported. Unreadable, or recorded against a different project: nothing on disk is tracked, so nothing is cleaned up, and the run records only what it materializes.

​

Breaking: facet remove decides what is declared under the lock

​

Adapter authors

​

Facets can ship non-asset files

• Skill companions — files beside a SKILL.md (references, scripts, templates). They install and remove atomically with their skill, and files you add to a skill directory yourself are preserved on removal.
• Top-level archive-only files — README.md, LICENSE, design notes. They ship in the archive but are never written to disk at install.

{
  "skills": {
    "code-review": {
      "description": "Code review guidelines",
      "files": ["references/style-guide.md"]
    }
  },
  "files": ["README.md", "LICENSE"]
}

​

First-class README authoring

​

Breaking: archive 0.2, per-file lockfiles, and naming

• Archive format 0.2. Every build now emits facetVersion: 0.2 with a complete per-entry hash map covering every file, asset or not. Consumers still accept legacy 0.1 archives during the compatibility window; the two are dispatched by exact version match, never numeric ordering. An archive whose version your CLI doesn’t support fails with upgrade guidance — run facet self-update.
• Lockfile 0.2. facets.lock records a per-file { path, integrity } record for every materialized file inside each asset, and install reconciles them before writing, reporting and repairing drift by exact path. A verified legacy alpha lockfile migrates automatically on a normal install. See Lockfile.
• Asset names. Skill, command, and agent names are now single-segment Agent Skills names — slash-namespaced names like viper-plans/planning are no longer valid in new manifests (use viper-planning). Skills and commands now share one namespace and can’t reuse a name.
• Primary files carry no front matter. Asset metadata lives in the manifest; a SKILL.md, agent, or command file with YAML front matter is now a build error. Supplementary files still ship verbatim.

​

Breaking: adapter API 0.0 → 0.1

facet adapter list                 # shows each adapter's declared API
facet adapter install my-adapter   # reinstall the newest compatible release

​

Rollout

​

facet remove prunes empty adapter directories

• Tidier working tree. Uninstalling a facet no longer leaves behind empty namespace folders that you’d otherwise have to delete by hand.
• No configuration. The behavior is automatic for the Claude Code and OpenCode adapters — no flags, no opt-in.
• Bounded to each adapter. Pruning stops at the adapter’s own root, so it can never walk into the rest of your project.

​

Server-side search for facet search

facet search plan        # sends ?q=plan; server ranks and pages the results
facet search             # no term; returns the first page unfiltered

• Results match the web UI. Ordering is consistent with what agentfacets.io shows, because both surfaces read the same server-ranked list.
• Better matching, no upgrade required. Improvements to registry search (typo tolerance, ranking, new sort orders) take effect immediately — the CLI just displays what the server sends.
• Old behavior removed. The client-side case-insensitive name substring filter is gone. If a term returns no matches on the server, the CLI now shows an empty result instead of falling back to local filtering.

​

Asset names now follow the Agent Skills grammar

• 1–64 characters long
• lowercase ASCII letters, digits, and hyphens only
• no leading, trailing, or consecutive hyphens

# Accepted (was rejected before):
facet modify skill 2fa --add

# Rejected (was accepted before):
facet modify skill MySkill --add
facet modify skill foo_bar --add
facet modify skill really-long-name-that-goes-well-past-sixty-four-characters-in-length --add

​

TypeScript 7 support

• @agent-facets/protocol
• @agent-facets/adapter
• @agent-facets/brand
• @agent-facets/adapter-claude-code
• @agent-facets/adapter-codex
• @agent-facets/adapter-opencode

​

Trailing newlines on generated JSON

• facets.lock
• install receipts and parallel-install lock payloads
• build manifests inside the .facet archive
• scaffolded facet.json (from facet create)
• cache integrity sidecars

​

The CLI is now agent-friendly

​

New command: facet instructions

facet instructions            # overview (default): the two workflows + index
facet instructions manifest   # facet.json structure + generated JSON Schema
facet instructions authoring  # scaffold → modify → verify, incl. adapter config
facet instructions usage      # add/update/remove facets; install adapter tooling

​

New command: facet modify

# Add an asset (manifest entry + scaffolded file), with a description
# and adapter config, in one call:
facet modify skill greet --add --description "Greets the user" \
  --adapter-claude-code '{"permission":{"bash":"ask"}}'

# Change a description, rename (moves the file too), or remove:
facet modify agent helper --description "Reviews code"
facet modify command run --rename start
facet modify skill greet --remove

# Set facet-level metadata:
facet modify facet --version 1.0.0 --private

​

facet create gains headless flags

facet create ./my-facet \
  --name my-facet --description "What it does" --version 0.1.0 \
  --skill greet --agent helper --command run --json

​

facet build --verify and --json

facet build --verify          # validate only; nothing written to dist/
facet build --verify --json   # machine-readable: { ok, errors, warnings, … }

​

Fix: subcommand --version is no longer shadowed

​

New command: facet remove

# Remove a single facet.
facet remove viper-plans

# rm is an alias.
facet rm viper-plans

# Remove several at once.
facet remove viper-plans rezi

​

Registry authentication is now bearer-token based

# 1. Environment variable (preferred for CI):
export FACET_TOKEN=fct_pub_…
facet publish

# 2. Or sign in interactively  -- verifies the token and saves it to
#    ~/.facet/credentials (mode 600):
facet login

​

New commands: login, whoami, logout

• facet login — guided sign-in. Paste a PAT; the CLI verifies it against the registry before saving it, so a typo or expired token fails fast instead of surfacing later at publish time. A browser sign-in option is shown as “coming soon”.
• facet whoami — prints the signed-in username, email, and tier, and notes when FACET_TOKEN is the active credential.
• facet logout — removes the saved credentials file. It makes no server call; revoke PATs in the web UI. If FACET_TOKEN is still set, it tells you so.

​

facet publish takes an optional directory

facet publish            # publish the facet in the current directory
facet publish ./cowsay   # publish the facet in ./cowsay

​

Registry errors render verbatim

​

Editing a version in facets.json now takes effect

# facets.json edited: cowsay 0.1.1 → 0.1.2
facet install          # fetches 0.1.2, updates the lockfile (was 0.1.1 → 0.1.2)

# facets.json edited to a version that doesn't exist
facet install          # fails: version not found; project left unchanged

​

New: facet install --frozen-lockfile

facet install --frozen-lockfile   # passes only if facets.json and facets.lock agree

​

One directory, one override

​

The new shape

$FACET_DIR/
  ├── bin/        # curl-installed binary
  ├── cache/      # content-addressed cache for fetched facets
  ├── adapters/   # installed adapter bundles
  └── locks/      # install advisory locks (one file per project)

​

What changed

​

FACET_BIN_OVERRIDE, by name

​

Project root: clean

​

Three layers, honestly named

• @agent-facets/protocol (NEW, public, Node-native, Node 22+) — the TypeScript reference implementation of the facet artifact specification. Schemas, bytes-validators, integrity verification, content hashing, deterministic tar layout, version-spec grammar, front-matter encoding, build validators. Pure data + cryptography. No subprocesses, no network, no developer-machine state.
• @agent-facets/engine (RENAMED from @agent-facets/core, made private) — the Bun-native CLI machinery. Install pipeline, registry HTTP client, adapter machinery, source resolvers, manifest mutations, cache, scaffold, edit, self-update, build pipeline orchestrator, gzip compression, path-based loaders. Internal to the monorepo; never published.
• agent-facets (the CLI binary, unchanged) — argv parsing, Ink TUI, error formatting, exit codes.

​

facet add and facet install converge

# The old two-step flow:
facet add github:owner/repo
facet install            # <-- no longer needed

# The new one-step flow:
facet add github:owner/repo

​

New source grammar

facet add viper-plans              # registry name (resolved version pinned)
facet add viper-plans@1.2.3        # exact version
facet add viper-plans@1.*          # major-pinned wildcard
facet add viper-plans@latest       # alias for the bare-name form
facet add github:owner/repo#main   # GitHub shorthand with a ref
facet add https://example.com/repo.git#v1.0.0
facet add git@github.com:owner/repo.git#main
facet add ./local-facets/my-plans  # local path inside the project
facet add a b c                    # multi-source: install several at once

​

Lockfile-driven, with bootstrap

• When a lockfile entry exists, that exact version is fetched. The manifest’s range is not re-resolved.
• When a lockfile entry doesn’t exist (first run, or a freshly-added manifest entry), the manifest specifier is resolved fresh.
• When facets.lock doesn’t exist yet, facet install bootstraps it — the same way bun install creates bun.lock.

​

Three-check integrity protocol

• Registry sources run three independent checks: cache vs. registry metadata, archive manifest vs. registry metadata, computed content vs. archive manifest. Each defends against a distinct adversary.
• Git sources run a single check: computed content vs. lockfile integrity. Defends against tag-move attacks.
• Local sources are trust-by-path.

​

Cache

​

Repaired outcome

​

Breaking changes

• git+ prefix is removed. Use plain https://...git or git@host:owner/repo instead. The new grammar accepts everything git+ did, just without the prefix.
• Caret, tilde, and comparator version ranges are rejected. Use 1.* for major-pinned, 1.2.* for minor-pinned, * or latest for unpinned, or 1.2.3 for exact. The @latest alias and bare-name form both produce the same result as *.
• facet install --dry-run is gone. No replacement; facet install always commits.
• facet install rejects positional arguments. To add a new facet to the project, use facet add.

​

Publish pipeline fixed across all packages

• agent-facets — the CLI
• @agent-facets/core and @agent-facets/adapter — authoring and adapter SDKs
• @agent-facets/adapter-claude-code, @agent-facets/adapter-opencode, and @agent-facets/adapter-codex — first-party adapters

curl -fsSL https://agentfacets.io/install | bash

npm install -g agent-facets

​

Mobile-responsive landing page

• Mobile navigation — the nav bar collapses into a slide-down menu on screens ≤ 1024 px wide, with all links accessible from a single tap.
• Adapted CLI demo — the interactive terminal demo skips the widest step on small screens so it fits without horizontal scrolling.
• Stacked sections — the explainer, hero, and footer all reflow into a clean single-column layout on narrow viewports.
• Registry CTA — on mobile, the install command is replaced with a link to agentfacets.io so you can browse facets without needing a terminal.

​

agentfacets.io landing page

curl -fsSL https://agentfacets.io/install | bash

​

New docs URL

​

facet add and facet install

facet add github:owner/repo
facet add https://github.com/owner/repo.git
facet add ./local-facet

• Lockfile diffing — only changed assets are written on each run.
• Rollback on failure — if something goes wrong mid-install, changes are reversed automatically.
• Concurrent safety — an atomic install lock prevents two facet install runs from interfering with each other.
• --verbose — full pipeline trace for debugging.

​

New install URL

curl -fsSL https://agentfacets.io/install | bash

npm install -g agent-facets

​

Self-contained adapter bundles

​

Adapter SDK and first-party adapters

• Claude Code
• OpenCode
• Codex (early access — installable, but asset materialization via facet install is coming soon)

facet adapter install
facet adapter list
facet adapter remove <name>

​

Self-contained .facet archives