@sandgarden/miranda 0.1.86 → 0.1.89

package/collector/stub.sh

@@ -44,15 +44,15 @@
 # now downloads the same release from "sandgardenhq/plugins" with the
 # "miranda-collector" prefix (#813). They stay placeholders rather than
 # literals so the release host can move without editing this file.
-BUILD_VERSION="dfe686cb61ce"
-RELEASE_TAG="collector-dfe686cb61ce"
+BUILD_VERSION="d9f84d746201"
+RELEASE_TAG="collector-d9f84d746201"
 RELEASE_REPO="sandgardenhq/plugins"
 ASSET_PREFIX="miranda-collector"
-CHECKSUM_DARWIN_ARM64="58b322fa26b3f2b7d2d6796d7f041b03916c78bc3fe34298157d812524697adb"
-CHECKSUM_DARWIN_X64="2de39f78f59bf4fe2482e75ccd182d30e2881400a1d3d662bcb376e54a24e1af"
-CHECKSUM_LINUX_X64="ee4f23586c6a96b86c3a1bcc98b37568c8de3e459cd1c1616096cbe3d8c30d37"
-CHECKSUM_LINUX_ARM64="aa93bc71849dd295817d907f20865bdda1560145b46fbcc850b6b67293bc1a62"
-CHECKSUM_WINDOWS_X64="e4024913af817202bc83e07fb3527ce6fb8ad75527c593e64c49118c11fa63ba"
+CHECKSUM_DARWIN_ARM64="a7bcd2b373d1862764c693f9a806549ab8dac83c5e51e4c14d65d842b83d4214"
+CHECKSUM_DARWIN_X64="4a94c252717e69ec1113a9b17c7478949229b9b402f5ab62f4bba2d4977048ca"
+CHECKSUM_LINUX_X64="453fcff80977921ef6b2ab799f88339c23e4d6ad744410d8dfc2caab239814c5"
+CHECKSUM_LINUX_ARM64="0eaa33f9cf12ae3cf5d41ecd2d1516499bd25958b360c24d07f54ed383616f26"
+CHECKSUM_WINDOWS_X64="b5a7034625929c1517bca0923396e10bc6a97564a946a6a4e678e7cd5d359d85"
 
 # A download lock older than this is a downloader that died mid-run: take it
 # over (mirrors the collector's sweep-lock staleness cutoff).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandgarden/miranda",
-  "version": "0.1.86",
+  "version": "0.1.89",
   "type": "module",
   "description": "Miranda OpenCode plugin — token-usage tracking skill + the gloria.dev MCP server's scoped /miranda tools.",
   "main": "index.js",

package/skills/setting-up-usage-tracking/SKILL.md

@@ -22,7 +22,7 @@ gets collected. Two files carry that:
 Then, once those are wired, enrol this machine so the collector daemon the
 Miranda plugin installs actually starts reporting usage, and make sure this
 repository is a Miranda project — the collector attributes a session to a
-project only when the session's `origin` remote matches one, so an
+project only when the session's `origin` remote matches one of a project's repositories, so an
 unregistered repository's spend all lands in **Unassigned**.
 
 Never modify the user's files without showing them exactly what will change
@@ -312,34 +312,64 @@ spend stops landing in Unassigned. Use the `miranda` MCP tools only.
 
    Change nothing else — not even letter case.
 
-3. **Look for a match.** Call `list_projects`, normalize each project's
-   `repoUrl` the same way (older rows can carry a trailing `/` or `.git`), and
-   compare exactly, case-sensitive — ingest matches the same way, so a
-   case-only difference is not a match. If a project matches, name the
-   existing project — its name and slug (all of them, if more than one
-   matches) — say spend from this repository is already attributed to it, and
-   register nothing.
+3. **Look for a match.** A project owns a set of repositories. Call
+   `list_projects`, normalize every URL in each project's `repoUrls` (the
+   project's repositories, its primary first) the same way (older rows can
+   carry a trailing `/` or `.git`), and compare exactly, case-sensitive —
+   ingest matches the same way, so a case-only difference is not a match.
+   Compare against all of them, not just the primary `repoUrl`: a repository
+   attached to a project is that project's as much as its primary is. If a
+   project matches, name the existing project — its name and slug (all of
+   them, if more than one matches) — say spend from this repository is
+   already attributed to it, and register nothing. Never overwrite an existing
+   description, even a blank or weak one: a person may have written it, and
+   they can edit it on the project's page.
 
 4. **Register when nothing matches.** Call `register_project` with
-   `{ "project": { "slug": …, "name": …, "repoUrl": <normalized URL> } }`:
+   `{ "project": { "slug": …, "name": …, "description": …, "repoUrls": [<normalized URL>] } }`:
    - `name` — the repository name: the last path segment of the normalized
      URL (`https://github.com/sandgardenhq/gloria.dev` → `gloria.dev`);
    - `slug` — that name lowercased, every run of characters outside `a-z0-9`
-     replaced by `-`, leading and trailing `-` trimmed (`gloria-dev`).
+     replaced by `-`, leading and trailing `-` trimmed (`gloria-dev`);
+   - `description` — one or two plain sentences, at most about 300
+     characters, saying what this project is and what it does, written from
+     what you can read at the repo root: the README first, then the manifest's
+     own description (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`
+     and the like), the agent instruction file, and the top-level layout. Be
+     specific: say who or what it serves and the main things it does, e.g.
+     "Next.js dashboard and Cloudflare Workers API that monitors a team's
+     third-party service dependencies and alerts on outages." Not the
+     project's name or its URL restated, no boilerplate ("A software
+     project", "This repository contains code"), no markdown. Never claim a
+     capability, user or integration the files don't show. If they show too
+     little to say anything concrete, omit `description` rather than guess.
+     The developer can edit it on the project's page afterwards.
 
    `register_project` **upserts by slug**: sending a slug some other project
    already has overwrites that project's name and repository. So if
-   `list_projects` already has the slug — whatever its `repoUrl`, set or not —
+   `list_projects` already has the slug — whatever its `repoUrls`, set or not —
    or the slug came out empty, use `<owner>-<repo>` built the same way
    (`sandgardenhq-gloria-dev`). `<owner>` is the path segment before the
    repository name (for `https://gitlab.com/group/sub/repo`, `sub`). If that is
    taken too, append a number to it — `<owner>-<repo>-2`, `-3`, … — until it
    is free. Slugs can't be changed later, so never guess past this rule.
 
+   If the result's `status` is `"held_by"`, another project already holds
+   this repository (it was attached after your `list_projects` call, or the
+   comparison missed it): nothing was created. Name that project from
+   `heldBy` (its slug and name), say this repository's spend is already
+   attributed to it, and register nothing more.
+
+   Registering never attaches: you can't tell from the code whether two
+   repositories are one product, and attaching moves spend between projects.
+   Never call `attach_project_repository` yourself.
+
 5. **Report what happened** in step 7, from the result's `project` and
    `backfill`:
    - the `slug` it registered under (and the name, when it isn't the same as
      the slug);
+   - the description it saved, quoted, so the developer can correct it on the
+     project's page — or that you sent none, and why;
    - `backfill.status` `"ran"` with `sessionCount` above 0 — that many earlier
      sessions moved from Unassigned onto the project, worth `spendMicros` ÷
      1,000,000 dollars (round to cents), the earliest from `earliestSessionAt`
@@ -353,6 +383,18 @@ spend stops landing in Unassigned. Use the `miranda` MCP tools only.
    - in every case, spend from more than 80 days before today stays in
      Unassigned.
 
+6. **Say how to attach instead.** After registering, tell the user that if
+   this repository is part of an existing product rather than a product of
+   its own, an org admin (`settings:manage`) can attach it to that product's
+   project: on the new project's page in Miranda, **Merge into…** that
+   project, which attaches this repository to it and moves the spend that
+   just moved here along with it. (`attach_project_repository` attaches a
+   repository no active project holds, so it won't take this one while the
+   new project does — it's how an admin adds a repository that isn't
+   registered yet.) Name the org's other projects from `list_projects` (name
+   and slug; the first ten and how many more, if there are more than ten) so
+   they can pick one. Skip this when the org had no other project.
+
 If `list_projects` or `register_project` fails with a transient error (a
 dropped connection, a timeout), retry it once. If it still fails, or the
 `miranda` MCP server isn't connected, or the call returns an error — say so,

package/skills/setting-up-usage-tracking/USING-MIRANDA.md

@@ -13,7 +13,8 @@ Miranda is available two ways, and both apply to you:
   `get_my_effectiveness`, `get_my_workflow`, `get_my_tracking_status`,
   `assign_my_session_work_item`, the managers-only `get_team_effectiveness`,
   plus the shared
-  `get_info`/`list_projects`/`register_project`/`put_project_github_info` —
+  `get_info`/`list_projects`/`register_project`/`put_project_github_info` and
+  the admin-only `attach_project_repository`/`detach_project_repository` —
   the same rows the
   `gloria` server exposes, since Miranda and gloria share one database).
 - **The usage-collector hooks** installed with the Miranda plugin (Claude
@@ -124,10 +125,12 @@ session's cost isn't available yet rather than estimating it.
 ## When this repository isn't a project
 
 Miranda attributes a session to a project only when the session's `origin`
-remote matches a registered project's `repoUrl`; everything else lands in
-**Unassigned**, where no per-project or per-issue figure can see it. So when a
+remote matches one of a registered project's repositories (a project can own
+several; `list_projects` lists them as `repoUrls`, the primary first);
+everything else lands in **Unassigned**, where no per-project or per-issue
+figure can see it. So when a
 Miranda tool result shows this repository isn't a project — `list_projects`
-has no project whose `repoUrl` matches this repository's `origin`, or
+has no project with this repository's `origin` among its `repoUrls`, or
 `get_my_tracking_status` or `get_my_spend` puts this repository's sessions in
 Unassigned — register it, **without asking**. Registering is part of tracking
 this repository, which the team has already adopted.
@@ -137,11 +140,15 @@ project" step: read `origin` with
 `git remote get-url origin | sed -E 's#://[^/@]*@#://#'` (the `sed` keeps a
 token embedded in the remote out of the transcript), normalize it (SSH forms
 to `https://`, no userinfo, no `.git` or trailing `/`), compare it against
-every project's `repoUrl` normalized the same way, and when nothing matches, call `register_project` with the repository's name
+every URL in every project's `repoUrls` normalized the same way, and when nothing matches, call `register_project` with the repository's name
 and a slug no existing project has. Then tell the user the slug and what the
 result's `backfill` moved out of Unassigned (sessions, dollars, earliest
-session). Spend older than 80 days stays in Unassigned. No `origin` remote
-means nothing to match — say so and move on.
+session), and that if this repository belongs to an existing product an
+admin can make it part of that project instead (the skill's step says how,
+naming the org's projects). Never call `attach_project_repository` yourself:
+whether two repositories are one product is the team's call. Spend older
+than 80 days stays in Unassigned. No `origin` remote means nothing to match
+— say so and move on.
 
 ## Setting up usage tracking
 
@@ -157,17 +164,28 @@ this end to end.
 ## MCP tools reference
 
 All tools run as the authenticated user against their active organization.
-Reads need `inventory:read` (any member); writes need `inventory:write`.
+Reads need `inventory:read` (any member); writes need `inventory:write` unless noted below.
 
 - `get_info` — org id/name/slug. Cheap; call it first when you need org
   context or to check the `miranda` MCP server is reachable.
-- `list_projects` — every project in the org, with its `repoUrl`. How you
-  tell whether this repository is a project yet.
+- `list_projects` — every project in the org, with `repoUrls` (every
+  repository it owns, the primary first) and `repoUrl` (the primary). How you
+  tell whether this repository is a project yet: it is when its `origin`
+  matches any of a project's `repoUrls`.
 - `register_project`, `put_project_github_info` — register this repo as a
-  gloria.dev/Miranda project (the same rows either server writes). Upserts by
-  slug, so never send a slug another project already has. When it gives a
-  project a `repoUrl`, its `backfill` reports the repository's earlier
-  Unassigned spend that moved onto it.
+  gloria.dev/Miranda project (the same rows either server writes). Takes
+  `repoUrls`, the first the primary. Upserts by slug, so never send a slug
+  another project already has; on an existing project it only adds
+  repositories. Creating refuses a repository another project holds — status
+  `"held_by"` with `heldBy` naming it. For each repository it attaches, the
+  earlier Unassigned spend moves onto the project; `backfill` reports the
+  total.
+- `attach_project_repository`, `detach_project_repository` — add a repository
+  to an existing project, or take one off (`projectSlug`, `repoUrl`). Require
+  `settings:manage` (an org admin); call them only when the user asks.
+  Attaching moves the repository's last 80 days of Unassigned spend onto the
+  project and reports it as `backfill`; detaching leaves attributed spend
+  where it is.
 - `tag_session_work_item` — declare the GitHub issue this session is working
   on (bare issue number, `gh:482`, or a full issue URL). Session-local — it
   writes only to this session's own transcript, never the database — the