guild-cli 0.4.0__tar.gz → 0.4.2__tar.gz

guild_cli-0.4.2/.claude/skills/guild/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: guild
+description: >
+  Run guildmaster's skills-supplier overview and narrate it. Run `guild
+  overview` (via scripts/overview.sh) for the deterministic evidence pack — the
+  canonical skill set + versions/origins, the docs/skill-sources.md ledger, and
+  skills-scoped drift signals — then narrate three separated layers: observed
+  facts, inferred relationships, and suggestions (each naming the command that
+  enacts it). Use when an operator asks "what skills do we supply", "who
+  consumes what", "is anything drifting", or "what should I teach next".
+  Skills-scoped and reflect-only — it surfaces and interprets supplier-side
+  skill/version signals; it does NOT narrate the agent relationship graph or
+  judge alignment (that stays with steward's org-overview / steward doctor).
+  The skills-scoped excerpt of steward's `org-overview` narration contract
+  (cite-don't-import, issue #12).
+type: command
+---
+
+# guild — narrate guildmaster's own supplier surfaces
+
+guildmaster is the mesh's skills **supplier**, and it owns the *inventory*
+surfaces ([issue #12](https://github.com/agentculture/guildmaster/issues/12)).
+The per-agent half (`guild show`) is backed by the vendored `agent-config`
+skill. **This skill is the supplier half: the affordance for `guild overview`.**
+It houses the scripts that run guildmaster's own read-only CLI surfaces and the
+contract for narrating them — `overview` is the one script today.
+
+Unlike the vendored skills, this one is **guildmaster's own** (origin =
+`guildmaster`, not cited from steward): `guild overview` is a pure-Python,
+read-only CLI verb, and `scripts/overview.sh` is the thin deterministic wrapper
+that invokes it. The script picks how to call `guild` (installed console
+script → `uv run` → `python -m guild`) and delegates; it interprets nothing.
+
+**The load-bearing split** (this is the skills-scoped excerpt of steward's
+`org-overview` narration contract — issue #12, cite-don't-import):
+
+- **The CLI (`guild overview`) emits only deterministic facts** — the canonical
+  skill set, the ledger view, and neutral drift signals. No LLM, no
+  interpretation, mutates nothing.
+- **This skill is where the agent interprets** — turning those facts into
+  inferred relationships and suggestions. **Never present an inference as a
+  fact**, and keep the layers in separate sections.
+
+## What `overview` answers
+
+A skills-scoped evidence pack — **not** `steward overview`'s ecosystem
+relationship graph (issue #12: inventory → guildmaster; judgment → steward):
+
+1. **Canonical skill set + versions** — every skill guildmaster supplies, its
+   origin (`guildmaster`, or a sibling it only re-broadcasts), and the current
+   canonical version, plus per-skill consumers.
+2. **Ledger view** — who-consumes-which-skill, read from `docs/skill-sources.md`.
+3. **Drift signals** — canonical skills no one consumes, canonical skills the
+   ledger doesn't track yet, and per-agent kit gaps. These feed `teach` /
+   `onboard`.
+
+**Pre-cutover** the guildmaster ledger is still a consumer-side view with no
+"Downstream" column, so the supplier ledger is empty and drift is inactive; the
+verb reports the canonical set and says so plainly (see `docs/cutover.md`).
+
+**`--scope mesh`** is the ledger-free alternative: it surveys every agent in the
+workspace (`<workspace>/*/culture.yaml`) live off the filesystem and reports, per
+agent, each canonical skill as **current** / **stale** (the agent's copy differs
+from guildmaster's by content fingerprint) / **missing**, plus any non-canonical
+"extra" skills. Use it to answer "what's missing or stale, and where" *today*,
+without waiting for the cutover. Still skills-scoped — no relationship graph.
+
+## When to use
+
+- An operator asks "what skills do we supply" / "what's the canonical set".
+- "Who has skill `<x>`?" / "who consumes what?" / "is anything drifting?"
+- "What should I `teach` next?" — overview's gaps are the input to `teach`.
+- Before `guild teach` / `guild onboard`, to see uncovered skills and kit gaps.
+
+## How to run
+
+One script. Pick the scope (or just run `guild overview`, which this wraps):
+
+```bash
+# Whole mesh — the canonical set + ledger + drift across all agents (default)
+.claude/skills/guild/scripts/overview.sh
+
+# One agent — that agent's kit + gaps (first positional → --scope self)
+.claude/skills/guild/scripts/overview.sh daria
+
+# Mesh survey — every agent's skills + missing/stale, live off the filesystem
+.claude/skills/guild/scripts/overview.sh --scope mesh
+
+# Machine-readable evidence for precise reasoning
+.claude/skills/guild/scripts/overview.sh --json
+.claude/skills/guild/scripts/overview.sh --scope mesh --json
+```
+
+The script prints the CLI's markdown by default: the canonical-skill table, a
+ledger section, and a drift section. The exact per-skill consumer and gap lists
+live in `--json`.
+
+## Narrate three layers — never blur them
+
+`guild overview` emits only deterministic facts; this skill is where you
+interpret them. Keep the three layers in separate sections, and never present
+an inference as a fact:
+
+1. **Observed facts.** Summarize the canonical set + versions/origins and the
+   ledger view in your own words — lead with what the counts reveal (the
+   canonical set, who's behind, who's unregistered). State only what the CLI
+   reported; don't reproduce the raw signal lists verbatim (read `--json` only
+   when you need an exact list to act on). Pre-cutover, say so plainly: the
+   ledger has no downstream column yet, so consumers are empty and drift is
+   inactive.
+2. **Inferred relationships** (mark clearly as inferred). Connect facts no
+   single ledger row states outright — e.g. two consumers vendored from the
+   same upstream skill *both* lag a canonical bump (a shared exposure), or a
+   skill only `guildmaster` carries is a single point of supply.
+3. **Suggestions** (kept separate from facts, and *named, not run*). Seed these
+   from the skills-scoped drift signals — for each, name the concrete next step
+   and the command that enacts it, then stop.
+
+### Signal → suggestion (skills-scoped only)
+
+These are the **skill/version** signals `guild overview` emits — guildmaster's
+supplier lane:
+
+| Drift signal (from `guild overview`) | Reading | Named follow-up — name it, do NOT auto-run |
+|--------------------------------------|---------|--------------------------------------------|
+| `unledgered_skills` | a canonical skill the ledger doesn't track (no owner row) | Fix the ledger: add it to `docs/skill-sources.md` |
+| `uncovered_skills` | a canonical skill no agent consumes (orphan) | Confirm intentional, then `teach` it, or retire it |
+| `agent_gaps` (per-agent missing skill) | a consumer behind / missing a skill | `guild teach --skill <name> --to <agent>` to close the gap |
+| agent not registered in the ledger | a sibling not yet onboarded | `guild onboard --agent <owner/repo>` |
+| consumer behind the canonical pin (post-cutover) | a team on an outdated procedure | Re-vendor: `guild teach` / `onboard` to the current pin |
+
+### Out of scope — steward's lane
+
+The **relationship** signals — `overlap`, `over-connected-agent`,
+`isolated-repo` — and the typed agent relationship graph are **not** narrated
+here. Those belong to steward's `org-overview` / `steward overview`. guildmaster
+narrates skills/version drift, not the ecosystem graph or alignment judgment.
+
+### Reflect-only
+
+This skill **sees, reflects, and suggests — it does not act.** For every
+suggestion, name the concrete next step and the command that enacts it, then
+stop. Editing the ledger, filing an issue, or running `teach` / `onboard` is a
+separate, explicit step the operator chooses. The skill writes nothing to disk
+and mutates no repo — output is the chat conversation only. Read-only: no
+`--apply`, no mutation, no network/LLM call.

guild_cli-0.4.2/.claude/skills/guild/scripts/overview.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+set -euo pipefail
+# overview — assemble the `guild overview` skills-supplier evidence pack for
+# narration.
+#
+# The guildmaster agent runs this, then narrates the supplier view (the
+# canonical skill set + versions/origins, the docs/skill-sources.md ledger, and
+# the drift signals that feed `teach` / `onboard`). See SKILL.md.
+# Deterministic glue only: resolve guildmaster's repo root, run from there,
+# resolve how to invoke guild, pick the scope, and delegate to `guild overview`.
+# No interpretation.
+#
+# Usage:
+#   overview.sh                  # whole ledger across the mesh (--scope all)
+#   overview.sh <agent>          # one agent's kit + gaps       (--scope self)
+#   overview.sh --scope mesh     # live filesystem survey of every agent
+#   overview.sh --json           # all, JSON evidence
+#   overview.sh <agent> --json   # one agent, JSON evidence
+#
+# Contract: the FIRST argument, if it does not start with '-', is the agent
+# (self scope). All remaining arguments pass through to `guild overview`.
+#
+# Exit codes:
+#   0   success (delegates to `guild overview`; its exit code propagates)
+#   1   environment error (no way to invoke guild)
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Resolve guildmaster's repo root and run from there, so `guild overview` always
+# reports guildmaster's canonical set regardless of the caller's working
+# directory (the CLI reads its repo from cwd). Prefer git (robust); fall back to
+# climbing out of the fixed .claude/skills/<name>/scripts/ layout when git is
+# unavailable.
+REPO_ROOT="$(git -C "$SCRIPT_DIR" rev-parse --show-toplevel 2>/dev/null || true)"
+if [ -z "$REPO_ROOT" ]; then
+    REPO_ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+fi
+cd "$REPO_ROOT"
+
+# Resolve how to invoke guild: installed console script, then uv, then module.
+if command -v guild >/dev/null 2>&1; then
+    GUILD=(guild)
+elif [ -f "$REPO_ROOT/pyproject.toml" ] && command -v uv >/dev/null 2>&1; then
+    GUILD=(uv run --project "$REPO_ROOT" guild)
+elif command -v python3 >/dev/null 2>&1; then
+    GUILD=(python3 -m guild)
+else
+    echo "overview: cannot invoke guild (need 'guild', 'uv', or 'python3' on PATH)" >&2
+    exit 1
+fi
+
+# Honor an explicit --scope passed through (advanced use); otherwise pick one.
+has_scope=false
+for arg in "$@"; do
+    case "$arg" in
+        --scope | --scope=*)
+            has_scope=true
+            break
+            ;;
+    esac
+done
+
+overview_args=()
+if [ "$#" -gt 0 ] && [[ "$1" != -* ]]; then
+    # First arg is an agent → one-agent (self) scope.
+    agent="$1"
+    shift
+    $has_scope || overview_args+=(--scope self)
+    overview_args+=("$agent")
+else
+    # No leading agent → whole-ledger (all) view.
+    $has_scope || overview_args+=(--scope all)
+fi
+overview_args+=("$@")
+
+exec "${GUILD[@]}" overview "${overview_args[@]}"

{guild_cli-0.4.0 → guild_cli-0.4.2}/CHANGELOG.md

@@ -5,6 +5,58 @@ All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/). This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.2] - 2026-05-24
+
+### Added
+
+- **`guild overview --scope mesh`** — a live filesystem survey of the whole
+  workspace, the answer to "what skills does every agent have, and what's
+  missing or stale, and where" without waiting for the cutover. Discovers every
+  agent (`<workspace>/*/culture.yaml`, via the new `discover_agents` helper) and
+  reports, per agent, each canonical skill as **current** / **stale** (the
+  agent's copy differs from guildmaster's by content fingerprint —
+  `skill_fingerprint`) / **missing**, plus any non-canonical "extra" skills.
+  Markdown + `--json`; `--workspace-root DIR` overrides the surveyed root
+  (default: the parent of this repo). Read-only, inventory only — no
+  dependency/relationship graph (that stays steward's lane). The existing
+  ledger-based `--scope all` / `--scope self` are unchanged.
+
+### Changed
+
+### Fixed
+
+- Mesh-survey robustness (Qodo review on #15): `discover_agents` and
+  `iter_skills` now skip non-UTF-8 / unreadable `culture.yaml` and `SKILL.md`
+  (one bad file in a surveyed repo no longer crashes the run), and
+  `skill_fingerprint` skips symlinks (never follows links outside the skill dir;
+  keeps the digest deterministic).
+
+## [0.4.1] - 2026-05-24
+
+### Added
+
+- **`guild` skill** — the backing affordance + narration skill for `guild
+  overview`, the supplier-overview half of the inventory split (sibling to the
+  vendored `agent-config` skill that backs `guild show`). `scripts/overview.sh`
+  is a deterministic wrapper that resolves how to invoke `guild` (installed →
+  `uv` → `python -m guild`) and delegates to `guild overview`; `SKILL.md` is the
+  **skills-scoped excerpt of steward's `org-overview` narration contract**
+  ([#12](https://github.com/agentculture/guildmaster/issues/12),
+  cite-don't-import): narrate three separated layers — observed facts, inferred
+  relationships, suggestions (each naming its enacting `teach` / `onboard` /
+  ledger command), reflect-only. Skills/version scope only — does NOT narrate
+  steward's relationship-graph signals (`overlap` / `over-connected-agent` /
+  `isolated-repo`). Recorded in `docs/skill-sources.md` as guildmaster-origin
+  (not vendored).
+
+### Changed
+
+- `SELF_SKILLS` now includes `guild` — guildmaster's own affordance skill is
+  excluded from the canonical kit it supplies to siblings (like `teach` /
+  `onboard`), since it wraps the `guild` binary and is meaningless elsewhere.
+
+### Fixed
+
 ## [0.4.0] - 2026-05-24
 
 ### Added

{guild_cli-0.4.0 → guild_cli-0.4.2}/CLAUDE.md

@@ -113,11 +113,17 @@ owns the mesh's *inventory* surfaces per
 **inventory → guildmaster; judgment ("how do agents relate / are they aligned?")
 → steward.** Neither verb clones `steward overview`'s relationship graph.
 
-- `guild overview [--scope all|self <agent>]` — the supplier view: canonical
-  skill set + versions/origins, the `docs/skill-sources.md` ledger, and drift
-  signals (uncovered skills, per-agent kit gaps). Pure-Python, read-only, **no
-  `--apply`**. Pre-cutover the ledger has no downstream column, so drift is
-  inactive and the verb says so (reads whichever ledger is authoritative).
+- `guild overview [--scope all|self <agent>|mesh]` — the supplier view:
+  canonical skill set + versions/origins, the `docs/skill-sources.md` ledger,
+  and drift signals (uncovered skills, per-agent kit gaps). Pure-Python,
+  read-only, **no `--apply`**. Pre-cutover the ledger has no downstream column,
+  so `--scope all`/`self` drift is inactive and the verb says so (reads
+  whichever ledger is authoritative). `--scope mesh` is the ledger-free
+  alternative: it surveys every agent in the workspace
+  (`<workspace>/*/culture.yaml`) live off the filesystem and reports, per agent,
+  each canonical skill as current / **stale** (content fingerprint differs from
+  guildmaster's copy) / **missing** — answering "what's missing or stale, and
+  where" today. Still inventory only — no relationship graph.
 - `guild show <path-or-suffix>` — one agent's full config: detected prompt file
   (`CLAUDE.md` / `AGENTS.md` / `GEMINI.md`), parallel `culture.yaml`, and the
   `.claude/skills` index. Thin wrapper that shells out to the vendored

{guild_cli-0.4.0 → guild_cli-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: guild-cli
-Version: 0.4.0
+Version: 0.4.2
 Summary: guildmaster — an agent and CLI that manages skills for the AgentCulture mesh.
 Project-URL: Homepage, https://github.com/agentculture/guildmaster
 Project-URL: Issues, https://github.com/agentculture/guildmaster/issues
@@ -104,12 +104,13 @@ read-only — no `--apply`, no mutation, no drift verdict (judgment stays with
 
 | Verb | What it does |
 |------|--------------|
-| `guild overview [--scope all\|self <agent>]` | The supplier view: the canonical skill set + versions/origins, the `docs/skill-sources.md` ledger, and drift signals (uncovered skills, per-agent kit gaps). Feeds `teach` / `onboard`. |
+| `guild overview [--scope all\|self <agent>\|mesh]` | The supplier view: the canonical skill set + versions/origins, the `docs/skill-sources.md` ledger, and drift signals (uncovered skills, per-agent kit gaps). Feeds `teach` / `onboard`. `--scope mesh` instead surveys every agent's vendored skills live off the filesystem and flags what's **missing**/**stale** per agent. |
 | `guild show <path-or-suffix>` | One agent's full config in one view — its detected prompt file (`CLAUDE.md` / `AGENTS.md` / `GEMINI.md`), its parallel `culture.yaml`, and its `.claude/skills` index. |
 
 ```bash
 uv run guild overview                       # whole ledger + canonical set
 uv run guild overview --scope self daria    # one agent's kit + gaps
+uv run guild overview --scope mesh          # live survey: every agent's skills + missing/stale
 uv run guild show ../culture                 # config by path
 uv run guild show daria                      # config by registered suffix
 uv run guild show ../culture --json          # structured config object

{guild_cli-0.4.0 → guild_cli-0.4.2}/README.md

@@ -86,12 +86,13 @@ read-only — no `--apply`, no mutation, no drift verdict (judgment stays with
 
 | Verb | What it does |
 |------|--------------|
-| `guild overview [--scope all\|self <agent>]` | The supplier view: the canonical skill set + versions/origins, the `docs/skill-sources.md` ledger, and drift signals (uncovered skills, per-agent kit gaps). Feeds `teach` / `onboard`. |
+| `guild overview [--scope all\|self <agent>\|mesh]` | The supplier view: the canonical skill set + versions/origins, the `docs/skill-sources.md` ledger, and drift signals (uncovered skills, per-agent kit gaps). Feeds `teach` / `onboard`. `--scope mesh` instead surveys every agent's vendored skills live off the filesystem and flags what's **missing**/**stale** per agent. |
 | `guild show <path-or-suffix>` | One agent's full config in one view — its detected prompt file (`CLAUDE.md` / `AGENTS.md` / `GEMINI.md`), its parallel `culture.yaml`, and its `.claude/skills` index. |
 
 ```bash
 uv run guild overview                       # whole ledger + canonical set
 uv run guild overview --scope self daria    # one agent's kit + gaps
+uv run guild overview --scope mesh          # live survey: every agent's skills + missing/stale
 uv run guild show ../culture                 # config by path
 uv run guild show daria                      # config by registered suffix
 uv run guild show ../culture --json          # structured config object

{guild_cli-0.4.0 → guild_cli-0.4.2}/docs/skill-sources.md

@@ -7,8 +7,8 @@ but it onboards as a consumer first, vendoring the canonical skill set like ever
 other sibling before taking over the upstream ledger, the
 `announce-skill-update` broadcast, and skill-version tracking. Until that
 ownership transfers, `steward` holds the live supplier ledger
-(`../steward/docs/skill-sources.md`) and this file records only what guildmaster
-itself vendors.
+(`../steward/docs/skill-sources.md`) and this file records the skills guildmaster
+vendors plus the few it originates itself.
 
 Everything here follows **cite, don't import**: each skill is *copied* into
 `.claude/skills/<name>/`, not symlinked or installed as a cross-repo dependency.
@@ -67,6 +67,18 @@ and harmless on `claude-code`. This is the only divergence from upstream.
 | `spec-to-plan` | `devague` (`agentculture/devague`, `../devague/.claude/skills/spec-to-plan/`) | Operator for the **spec→plan** leg (`devague plan ...`): seed from a converged frame, cover every coverage target with acceptance-gated, acyclically-ordered tasks, park unknowns as risks, `export` once the plan converges. New in devague 0.4.0. **Divergence:** `type: command` added. Runtime dep: `uv tool install devague`. |
 | `assign-to-workforce` | `devague` (`agentculture/devague`, `../devague/.claude/skills/assign-to-workforce/`) | Operator for the **implementation** leg: reads `devague plan waves` (read-only) and fans out independent tasks to one agent per task per wave in isolated git worktrees, with main-agent TDD-gated merges. Three human gates: spec / split plan / final PR. The CLI stays non-orchestrating ([devague#20](https://github.com/agentculture/devague/issues/20)). New in devague 0.10.0. **Divergence:** `type: command` added. Runtime deps: `uv tool install devague`, `git worktree`, the vendored `cicd` skill (for the gate-3 `agex pr open`). |
 
+## guildmaster-origin skills (origin = `guildmaster`)
+
+These are guildmaster's **own** skills — not vendored from anyone, so there is
+no upstream to re-sync from. They are the affordance + narration layer for
+guildmaster's own CLI surfaces: the CLI verb is the implementation, and the
+skill is how the resident agent knows when to reach for it and how to narrate
+the result.
+
+| Skill | Origin | Notes |
+|-------|--------|-------|
+| `guild` | `guildmaster` (this repo) | Houses guildmaster's own read-only supplier surfaces. Today: `scripts/overview.sh`, the wrapper backing the pure-Python `guild overview` verb ([#12](https://github.com/agentculture/guildmaster/issues/12)) — the skills-supplier half of the inventory split, sibling to the vendored `agent-config` skill that backs `guild show`. Its `SKILL.md` is the skills-scoped excerpt of steward's `org-overview` narration contract (three layers: facts / inferred / suggestions; reflect-only). Surfaces skills/version drift that feeds `teach` / `onboard`; does NOT narrate steward's relationship graph or judge alignment. |
+
 ## Vendoring policy
 
 - **Cite, don't import.** Skills are copied into this repo, not symlinked or

{guild_cli-0.4.0 → guild_cli-0.4.2}/guild/cli/_commands/overview.py

@@ -13,23 +13,33 @@ surfaces three things, **skills-scoped only** — it does not reproduce
   canonical skills the ledger doesn't track yet. These feed ``teach`` /
   ``onboard``.
 
+``--scope mesh`` is the live alternative to the ledger: instead of reading
+``docs/skill-sources.md``, it surveys every agent in the workspace
+(``<workspace>/*/culture.yaml``) straight off the filesystem and reports, per
+agent, which canonical skills are present / **stale** (the agent's copy differs
+from guildmaster's canonical copy by content fingerprint) / **missing**. This
+answers "what's missing or stale, and where" without waiting for the cutover —
+still skills-scoped, still no dependency/relationship graph.
+
 Read-only: no ``--apply``, no mutation, no network/LLM call. Pre-cutover the
 guildmaster ledger is still a consumer-side view with no "Downstream" column, so
-the supplier ledger is empty; the verb says so plainly and still reports the
-canonical set (see ``docs/cutover.md``).
+the supplier ledger is empty; ``--scope all``/``self`` say so plainly and still
+report the canonical set (see ``docs/cutover.md``), while ``--scope mesh`` does
+not depend on the ledger at all.
 """
 
 from __future__ import annotations
 
 import argparse
 import json
+from pathlib import Path
 
 from guild import __version__
 from guild.cli._commands import _broadcast
 from guild.cli._errors import EXIT_USER_ERROR, GuildError
 from guild.cli._output import emit_result
-from guild.cli._repo import repo_root
-from guild.skills import INBOUND_ORIGINS
+from guild.cli._repo import discover_agents, iter_skills, repo_root, skill_fingerprint
+from guild.skills import INBOUND_ORIGINS, SELF_SKILLS
 from guild.skills import ledger as _ledger
 
 LEDGER_PATH = "docs/skill-sources.md"
@@ -38,24 +48,37 @@ LEDGER_PATH = "docs/skill-sources.md"
 def register(sub: argparse._SubParsersAction) -> None:
     parser = sub.add_parser(
         "overview",
-        help="Skills-supplier overview: canonical set + ledger + drift (read-only).",
+        help="Skills-supplier overview: canonical set + ledger + drift, or a live mesh survey.",
         description=(
             "Report guildmaster's canonical skill set + versions, the "
-            "upstream/downstream ledger, and drift signals. Skills-scoped and "
-            "read-only — no --apply, no mutation. For one agent's full config "
-            "(prompt file + culture.yaml + skills), use `guild show <agent>`."
+            "upstream/downstream ledger, and drift signals (--scope all/self, "
+            "from the ledger); or survey every agent's vendored skills live from "
+            "the filesystem and flag what's missing or stale per agent (--scope "
+            "mesh). Skills-scoped and read-only — no --apply, no mutation, no "
+            "dependency/relationship graph (that is steward's lane). For one "
+            "agent's full config, use `guild show <agent>`."
         ),
     )
     parser.add_argument(
         "--scope",
-        choices=("all", "self"),
+        choices=("all", "self", "mesh"),
         default="all",
-        help="all = whole ledger across the mesh (default); self = one agent's kit + drift.",
+        help=(
+            "all = whole ledger across the mesh (default); self = one agent's "
+            "kit + drift (from the ledger); mesh = live filesystem survey of "
+            "every agent's skills + missing/stale signals."
+        ),
     )
     parser.add_argument(
         "agent",
         nargs="?",
-        help="Agent name — required with --scope self, ignored with --scope all.",
+        help="Agent name — required with --scope self; ignored with --scope all/mesh.",
+    )
+    parser.add_argument(
+        "--workspace-root",
+        type=Path,
+        default=None,
+        help="Workspace dir to survey for --scope mesh (default: the parent of this repo).",
     )
     parser.add_argument(
         "--json",
@@ -146,6 +169,57 @@ def _build_self(root, agent: str) -> dict:
     }
 
 
+def _build_mesh(root, workspace_root) -> dict:
+    """Live filesystem survey of every agent's vendored skills + drift.
+
+    Canonical reference is guildmaster's own supplied set (its ``.claude/skills``
+    minus ``SELF_SKILLS``); an agent's copy is **stale** when its content
+    fingerprint differs from guildmaster's, **missing** when absent. Inventory
+    only — no dependency/relationship graph (that judgment is steward's lane).
+    """
+    canonical = [s for s in iter_skills(root) if s.name not in SELF_SKILLS]
+    canonical_fp = {s.name: skill_fingerprint(s.path) for s in canonical}
+    canonical_names = [s.name for s in canonical]
+
+    agents_view: list[dict] = []
+    for agent in discover_agents(workspace_root):
+        by_name = {s.name: s for s in iter_skills(agent.repo_path)}
+        per_skill: list[dict] = []
+        missing: list[str] = []
+        stale: list[str] = []
+        for name in canonical_names:
+            skill = by_name.get(name)
+            if skill is None:
+                missing.append(name)
+                per_skill.append({"skill": name, "status": "missing", "fingerprint": ""})
+                continue
+            fingerprint = skill_fingerprint(skill.path)
+            status = "current" if fingerprint == canonical_fp[name] else "stale"
+            if status == "stale":
+                stale.append(name)
+            per_skill.append({"skill": name, "status": status, "fingerprint": fingerprint})
+        agents_view.append(
+            {
+                "suffix": agent.suffix,
+                "backend": agent.backend,
+                "repo": agent.repo_name,
+                "skills": sorted(by_name),
+                "missing": missing,
+                "stale": stale,
+                "extra": sorted(n for n in by_name if n not in canonical_fp),
+                "per_skill": per_skill,
+            }
+        )
+
+    return {
+        "scope": "mesh",
+        "version": __version__,
+        "workspace_root": str(workspace_root),
+        "canonical_skills": [{"name": n, "fingerprint": canonical_fp[n]} for n in canonical_names],
+        "agents": agents_view,
+    }
+
+
 def _names_or(names, empty: str = "none") -> str:
     """Backtick-join *names*, or *empty* when there are none."""
     return ", ".join(f"`{n}`" for n in names) or empty
@@ -247,9 +321,74 @@ def _render_self(data: dict) -> str:
     return "\n".join(lines)
 
 
+def _count_or_dash(names) -> str:
+    """The count of *names*, or an em dash when there are none."""
+    return str(len(names)) if names else "—"
+
+
+def _render_mesh(data: dict) -> str:
+    agents = data["agents"]
+    canonical = data["canonical_skills"]
+    lines = [
+        "# guild overview — mesh skill inventory (scope: mesh)",
+        "",
+        f"guild {data['version']} · workspace: `{data['workspace_root']}` · "
+        f"{len(agents)} agent(s) · canonical set: {len(canonical)} skill(s)",
+        "",
+    ]
+    if not agents:
+        lines += [
+            "No agents found — no `*/culture.yaml` under the workspace root. Pass "
+            "`--workspace-root DIR` to point at the directory holding the sibling repos.",
+        ]
+        return "\n".join(lines)
+
+    lines += [
+        "## Agents",
+        "",
+        "| Agent | Backend | Repo | Skills | Missing | Stale |",
+        "|-------|---------|------|--------|---------|-------|",
+    ]
+    for a in agents:
+        lines.append(
+            f"| `{a['suffix']}` | {a['backend'] or '—'} | `{a['repo']}` | "
+            f"{len(a['skills'])} | {_count_or_dash(a['missing'])} | "
+            f"{_count_or_dash(a['stale'])} |"
+        )
+
+    drifting = [a for a in agents if a["missing"] or a["stale"]]
+    lines += ["", "## Missing & stale detail", ""]
+    if not drifting:
+        lines.append("Every agent's vendored copies match guildmaster's canonical set.")
+    else:
+        for a in drifting:
+            parts = []
+            if a["stale"]:
+                parts.append("stale " + _names_or(a["stale"]))
+            if a["missing"]:
+                parts.append("missing " + _names_or(a["missing"]))
+            lines.append(f"- `{a['suffix']}` (`{a['repo']}`): " + "; ".join(parts))
+
+    lines += [
+        "",
+        "_Canonical = guildmaster's supplied set (its skills minus its own operator "
+        "verbs). \"Stale\" = the agent's copy differs from guildmaster's by content "
+        'fingerprint; "missing" = the agent lacks a canonical skill. Inventory only — '
+        "the dependency/relationship graph is steward's lane._",
+    ]
+    return "\n".join(lines)
+
+
 def _handle(args: argparse.Namespace) -> int:
     root = repo_root()
 
+    if args.scope != "self" and args.agent:
+        raise GuildError(
+            code=EXIT_USER_ERROR,
+            message="an agent name is only valid with --scope self",
+            remediation="drop the agent, or use `--scope self <agent>`",
+        )
+
     if args.scope == "self":
         if not args.agent:
             raise GuildError(
@@ -259,13 +398,11 @@ def _handle(args: argparse.Namespace) -> int:
             )
         data = _build_self(root, args.agent)
         rendered = _render_self(data)
-    else:
-        if args.agent:
-            raise GuildError(
-                code=EXIT_USER_ERROR,
-                message="an agent name is only valid with --scope self",
-                remediation="drop the agent, or use `--scope self <agent>`",
-            )
+    elif args.scope == "mesh":
+        workspace_root = (args.workspace_root or root.parent).expanduser().resolve()
+        data = _build_mesh(root, workspace_root)
+        rendered = _render_mesh(data)
+    else:  # all
         data = _build_all(root)
         rendered = _render_all(data)