Skip to content

t1k:ual

FieldValue
Modulet1k-ual
Version2.9.56
Effortmedium
ToolsBash, Glob, Grep, Read, Skill

Keywords: add asset to catalogue, asset advisory, asset catalogue, asset discovery, asset hold, contribute asset, do we already have, do we have this asset, existing asset, find asset, licence class, particle catalogue, reuse asset, sfx reuse, sprite reuse, studio asset catalogue, ual, ual pull, ual-contribute, vfx reuse

/t1k:ual
<what you need> [--engine cocos|unity]

The studio’s answer to “do we already have this asset?”, asked before anyone builds, buys or commissions one.

The catalogue is the only asset source. Search UAL, and nothing else. The knowledge-retrieval RAG and the Cocos code graph index code symbols, not assets — both measured 0 asset hits out of 5 asset-shaped probes. Never present either as a place an asset might live. The RAG gets one labelled post-miss lane for code that produces the effect (references/post-miss-lane.md); the code graph is never used, not even there.

The catalogue covers Cocos and Unity (the shipped snapshot’s own rows carry both engines; check the live split with statsOf, never quote a remembered one). A Unity ask is still answerable — do not treat “unity” as a coverage gap.

Before the first UAL call — the NetBird browser login

Section titled “Before the first UAL call — the NetBird browser login”

assets.the1studio.org sits behind the NetBird mesh proxy. Until the user has opened the site in a browser and signed in to NetBird there, every mcp__ual__* call and every script that hits the site returns an HTML page titled NetBird Service ("code":502 … "Connection Error", /__netbird__/assets/…). That is not an outage and not an empty catalogue: it is a missing browser login.

Run the preflight first: bun "$HOME/.claude/scripts/ual-netbird-preflight.cjs". The script ships with this module at core’s global scope, so that absolute path resolves from any repo you are standing in; a bare .claude/scripts/... resolves only inside a core checkout and fails elsewhere. It opens the site in the user’s browser (over SSH it prints the URL), polls until the NetBird page stops, and prints one JSON line {status, opened, url}. Exit 0 = UAL is reachable. Exit 1 (blocked) = not signed in: give the user the printed URL and stop. A NetBird 502 from an MCP call: run the preflight, then retry that call once. Never bypass the mesh gate.

IntentPath
“Do we have a confetti particle / a coin sprite / a click sfx?”Query
“Which project does this come from, is it safe to use?”Hold status
“Where is this asset already used?”Usage
“Put it in my project”Pull
“Nothing matched”Miss report
“What is even in the catalogue?”Stats
“Add this file to the studio catalogue”Contribute an asset
“Label / re-label assets”t1k:ual-label (separate skill)

Where the commands run — there is no ual binary, and no corpus here

Section titled “Where the commands run — there is no ual binary, and no corpus here”

Set UAL once and quote it: the studio path can contain a space, and an unquoted cd fails with exit 2. Then cd "$UAL". Every block below states its own cd; a block with none runs from $UAL. The setup snippet and the no-binary note are in references/where-commands-run.md.

Step 0 — pick the transport, and say which one you used

Section titled “Step 0 — pick the transport, and say which one you used”

Two exist. Detect, never assume, and name the one you used — a result that does not name its path cannot be reproduced.

  1. MCP (mcp__ual__asset_search et al.): the probe command and its status codes are in references/transport.md. A 401 with a WWW-Authenticate header means it is up and wants the studio bearer (gh auth login). A 404 or a connection failure means fall through: do not retry, and do not report it as “the catalogue is empty”.
  2. The shipped query paths: searchAssets / usageOf / statsOf (imported from packages/ual-web/src/tools.ts), or the CLI verb ual-find. Both report the same matches; ual-find also stamps each result with a live hold verdict. The verbs ual resolve and ual slot do not exist. Run a command before you document it.

No mcp__ual__* tool bound to this hop (a routed hop’s toolset omits it) ⇒ the curl probe above proves nothing about your hop, so skip it and use path 2. With no $UAL checkout either, no transport is available: report transport unavailable: mcp__ual__* not granted, no $UAL checkout and name the missing grant. That is not a miss and not an empty catalogue, so never answer “not in UAL” or an unverified reuse verdict. Raw HTTP to the endpoint is not a substitute unless you name it as the transport and it returned catalogue data.

Read references/cli-surface.md (which commands exist, which are still plans, exact exit codes) and references/query-recipes.md (the probe procedure, with every command and its observed output) before your first query.

searchAssets(c, {query, category, engine, kind, limit}) cuts the query on [^a-z0-9]+ into at most 8 distinct tokens and matches a row when every token is a substring of some searchable field, case-insensitively: id, title, examplePath, category, engine, labels or description. A token of 5+ characters that matches no field falls back to a one-edit typo search over title/examplePath words, so confetti and the studio’s own confeti/confetty find each other; there are no synonyms and no scoring beyond count descending. limit defaults to 10, capped at 50. Split a multi-word need into single tokens yourself, because the AND is exact and a phrase’s words rarely share one row; try the spellings a person would type, use the kind, category and engine filters, collapse duplicate titles, and report candidates with their count rather than an answer. The default MCP asset_search is hybrid (lexical + vector, fused by reciprocal rank) and can add rows no token matched; the three facts that change the search and the six-step probe: references/query.md.

Hold status — read this before recommending anything

Section titled “Hold status — read this before recommending anything”

The corpus mixes studio-owned content with content under an IP hold. A candidate you surface is not one you may recommend until its hold status is known.

Read the verdict off the row and never write one you did not read: hold is null (released), ip-gated or unknown; holdCause is null until UAL issue #19 lands. Report a held candidate as ip-gated — held; cause not recorded (issue #19). Live verdicts come from ual-find --source <corpus>. The reasoning, and why unknown counts as held: references/hold-verdicts.md.

One rule, both hold classes, written once: references/hold-and-licence.md owns the enum, the rule, and what “explicit acknowledgement” means. In one line:

  • ip-gated is never recommended. Not with an acknowledgement, not ever.
  • asset-store is held, cause: it is a vendor acquisition — pulling it re-distributes a purchased pack.
  • unknown is held too, and it is a lead only — though it does not by itself block a pull; the default refusal set is ip-gated.

Pulling a held asset needs --ack-hold "<reason>", which ships. The reason must be at least 15 characters and is recorded in the target’s assets/ual/ual-manifest.json as acknowledgedHold. An ip-gated pull without it is refused with exit 3. The flag does not lift a UUID collision, and the acknowledgement is a human decision recorded in the conversation — never something this skill asserts on the caller’s behalf.

Never write “cleared”, “safe”, “not held”, “licence-free” or “uploadable” about any variant whose verdict is not null — all misreadings of unknown, which is the absence of evidence. If a candidate matters enough to pull, state its verdict (and, where the row has one, its cause) and re-check against the live corpus with --source before the pull: a stamped null is evidence for the scan that produced it, not proof about today.

usageOf(c, id) returns the variants whose id (or sha256) equals the identity, with referenceCount summed over their instances: enough to say “studio standard or one-off?”. It is not a graph and lists no files. For a per-scene breakdown use mcp__ual__asset_usage when deployed; never imply a CLI equivalent exists. Command and output: references/usage.md.

Dry run first, always. ual-pull prints a plan and touches nothing unless --apply is passed. That default is deliberate and is not something to shortcut. The command: "ual pull <id>" that mcp__ual__asset_get returns is a hint, not a runnable verb: there is no ual binary, so run it as bun bin/ual-pull.mjs --variant <id> from $UAL/packages/ual-cli.

The dry-run command, the --source requirement (a real Cocos corpus, never .), the --gallery <dir> route that is the only way to dry-run an AssetHub row (sfx audio, vfx-unity .unitypackage), and the two exit-3 refusals (an ip-gated variant needs --ack-hold; a missing dependency needs --allow-missing; neither satisfies the other): references/pull.md.

Show the plan to the user. Apply only on explicit instruction — --apply writes into someone’s project, and this skill’s job is to make it a one-command, already-reviewed decision, not to make it for them.

Exit codes are load-bearing: 0 ran · 1 bad usage · 2 threw · 3 refused (unsafe to proceed — ambiguous query, unresolvable dependency, UUID collision, or an ip-gated variant with no acknowledgement). Exit 3 is an answer, not a failure: for an ambiguous query it lists every candidate id, and picking one for the user would be a guess. Surface the list, ask, re-run. Landing behaviour per engine: references/engine-notes.md.

A miss is a result, and it is what lets the project order or create the asset under placeholder-first handoff instead of guessing. Report it honestly:

  • “not in UAL”, then the scope you searched — every query verbatim, the snapshot’s scannedAt, its variant count. rules/negative-result-scope.md applies: a negative result is a claim about your search, not about the studio.

  • Know and state the coverage, and read it rather than remembering it. The snapshot holds three format classes — particle, sprite and audio — over two engines (searchFacets(...).engines reads cocos and unity), and it carries sprite and audio payload rows as well as particle effects. Get the split live before quoting it, because it moves with every scan (the command is in references/query.md):

    A need in a class those three do not cover — 3D, animation, or anything the kind filter returns nothing for — is “not covered by the catalogue as of <scan date>”, a coverage gap, never “we don’t have it”. Never “greenfield”, never an unscoped “we don’t have it”.

  • Name the next step: a genuine miss is the cue to raise a slot under theonekit-designer/.claude/modules/base/rules/placeholder-first-handoff.md (commit a deliberately ugly placeholder, wired and exercised), then order or build to it.

After the miss — one labelled lane, and only one

Section titled “After the miss — one labelled lane, and only one”

A miss entitles you to exactly one follow-up: a code-symbol search via mcp__knowledge-retrieval__doc_search, under its own heading and its own confidence statement. It returns code members, never assets, and its hits never enter the candidate table. The code graph is never used, and the asset corpus is never enrolled in the RAG. The required heading text and the three hard limits: references/post-miss-lane.md.

Quality gate — the shared golden-query eval

Section titled “Quality gate — the shared golden-query eval”

Retrieval quality is measured by one golden-query harness that ships in the UAL repo: catalogue/eval/queries.json and labels.json (provisional, agent-graded) feed packages/ual-web/scripts/eval-retrieval.mjs, and .github/workflows/ual-eval.yml runs it as a report, never a required check. Do not create a second query file, script or workflow, and label any hit figure a hit rate, not recall while the labels remain provisional (run.humanLabelled is 0). Details and open items: references/quality-gate.md.

“What is in there?” — statsOf(c) reads straight off the snapshot: totals (instances, variants, filesScanned, parseFailures), censusVariantCount, moduleUsage (enabled-descending), facets, and the header’s own scannedAt, schemaVersion, hashAlgorithm, hashMode. asset_stats is the MCP equivalent. Quote every number with scannedAt; a catalogue figure without its scan date is not a fact about today.

Putting a file into the contribution lane is a write to the studio store that outlives the session. Read references/contribute.md (the flow, the classes, the ack, the refusal codes) before the first call. The four rules that bind every contribution:

  1. Dry run, then the CLI. ual-contribute <file> --kind <kind> --licence <class> --dry-run first, then the same command without --dry-run. The server picks the destination from the licence; never choose it client-side. --dry-run checks flag shape only: a pass is not a policy pass.
  2. Classify honestly; when unsure, pick the stricter class. The strictest claim wins, so a weaker claim never loosens a stricter one. third-party-ripped needs --origin (refused without it). store-standard needs --purchase-ref, and without it the claim collapses to contributor-unverified. Only a person may contribute; a service identity is refused.
  3. Show the advisory text to the user before you ack, then wait. ual-pull of a warn or strong row prints the text and an ack code and refuses until --ack <code> --intent prototype|ship. Relay the text, take the person’s answer, and only then ack. Never ack on their behalf. The ack is an audit and UX gate, not a technical barrier; only the gated store is technical.
  4. Public bytes are locked for 365 days. Bytes in the public blob/ store sit under an R2 bucket lock and cannot be deleted inside it, so a wrong licence class cannot be undone by deletion. Classify conservatively before the first commit.
  • Search UAL only. No other backend is an asset source, at any step. The RAG gets the one labelled post-miss lane; the code graph is never used.
  • Read-only by default. --apply and any write into a project happen only on an explicit instruction, with the dry-run plan shown first. A contribution is the one store write: only for a person who asked for it, under the four rules above.
  • Never recommend an ip-gated asset; asset-store is held too. ip-gated is refused with exit 3 until a recorded --ack-hold (≥ 15 characters) is given. references/hold-and-licence.md owns the rule.
  • Never report a non-null hold as clearance, and never write a verdict you did not read. unknown is the absence of evidence.
  • Never state a catalogue fact without its scannedAt, and never state a coverage gap as an absence of the asset.
  • Never document a command you have not run. references/cli-surface.md separates verified-today from when-available for exactly this reason.
  • This skill has no engine-specific asset authority. What to do with a pulled asset in Cocos belongs to the Cocos kit; the UAL repo owns ingest and pull.