chore: merge main into perf/warm-run-shortcut

#510 lets a ready build serve only a CLI that reads what it holds, so
the warm run passes the CLI's linked-files capability to
findReusableBuild.

Author: harlan-zw

GLOSSARY.md

@@ -12,6 +12,8 @@ Shared terms match the skilld CLI glossary (`skilld-dev/skilld/GLOSSARY.md`). Th
 | Agent | the user's tool | Agent 1—N Agent target | "your agent" |
 | Repository | GitHub | Repository 1—N Skill | "repository" |
 | Artifact | skilld.dev API | Skill commit 1—1 Artifact | not shown |
+| linked file | Artifact attestation | Artifact 1—N linked file | not shown |
+| symbolic link | Skill folder, `symbolic-links` check result | Skill folder 1—N symbolic link | not shown |
 | source status | lockfile, skilld.dev API | Artifact 1—1 source status | "Verified", "Unverified", "Local" |
 | run | skilld CLI | Skill 1—1 run command | "run" |
 | demo | Skill page, homepage | Skill 1—N demo | "demo" |
@@ -262,6 +264,24 @@ Existing route paths, table names, and protocol fields keep their identifiers.
 
 **Never:** signature (bare), certificate, receipt.
 
+### linked file
+
+**Is:** a Skill file the Artifact attestation lists by path, size, and Git blob SHA, without packing its bytes. The skilld CLI reads it from GitHub at the attested commit and checks it against that SHA. Only a CLI that sends `Skilld-Capabilities: linked-files` gets one. See ADR-0013.
+
+**Never:** external file, remote asset, download, attachment.
+
+### omitted file
+
+**Is:** a Skill file left out of an Artifact for a size limit. The `omitted-files` check result names each one. A CLI that reads linked files gets a large file as a linked file instead.
+
+**Never:** skipped file, excluded file, dropped file.
+
+### symbolic link
+
+**Is:** a Git tree entry of mode `120000` whose blob holds a path. A build packs the files a link in the Skill folder names at the link path, or leaves the link out. The `symbolic-links` check result lists each one. See ADR-0014.
+
+**Never:** linked file (that is a file the CLI reads from GitHub), alias, shortcut, symlink in prose.
+
 ### check result
 
 **Is:** one named check, its version, its finding, and its outcome for one Artifact.

VISION.md

@@ -95,7 +95,7 @@ The filter for skilld-scoped work, precise enough to hold a proposal next to it
 
 ### 1. Provenance is the quality signal
 
-A Skill is trustworthy because you can see who wrote it and read it before you run it. Every surface that shows a Skill names the author. The Skill page links the exact source file in its repository; other surfaces link the Skill page, which is where a visitor inspects a Skill. Registry identity is frozen at admission (ADR-0002) so provenance URLs never rot. Machine-generated metadata is labeled as such and never dressed as authorship.
+A Skill is trustworthy because you can see who wrote it and read it before you run it. Every surface that shows a Skill names the author. The Skill page links the exact source file in its repository; other surfaces link the Skill page, which is where a visitor inspects a Skill. When GitHub moves a Repository, its Skills move to the new name and every old URL answers 301 (ADR-0015), so provenance URLs never rot. Machine-generated metadata is labeled as such and never dressed as authorship.
 
 **How to apply:** no Skill card, search result, or digest entry ships without its author and a link to its Skill page or its source. A layout that drops provenance to save space fails review. Trust signals (official repository, owner-verified) are earned facts, never editorial favors.
 

app/components/DemoStage.vue

@@ -56,6 +56,7 @@ const liveUrl = computed(() => live && !demo.video ? demo.liveUrl : null)
         :src="liveUrl"
         sandbox="allow-scripts"
         :title="`Live output of /${demo.name}`"
+        loading="lazy"
         class="demo-stage__frame"
       />
       <DemoMedia v-else :demo :eager play="visible" />

app/components/WeeklyEmailPreview.vue

@@ -8,8 +8,11 @@ import type { DigestDemoResponse } from '#layers/identity/server/api/digest/demo
 
 // A failed demo costs the section its picture, never its copy or its CTA:
 // `data` stays null on error and `hasDemo` gates the whole frame.
-const { data: demo } = await useFetch<DigestDemoResponse>('/api/digest/demo', {
+// Only the card and its row count reach the payload. The answer also carries
+// the whole email as `html`, which this preview never renders.
+const { data: demo } = await useFetch('/api/digest/demo', {
   key: 'home-digest-demo-v1',
+  transform: ({ card, rowCount }: DigestDemoResponse) => ({ card, rowCount }),
 })
 
 const hasDemo = computed(() => !!demo.value?.card && (demo.value?.rowCount ?? 0) > 0)

app/pages/index.vue

@@ -91,9 +91,10 @@ const [
     query: { limit: 24 },
     // The board ships only its head. The rest of the named Skills, with their
     // posts and star series, serve `/skills/trending` and would ride in this
-    // page's payload unread.
+    // page's payload unread. The texture reads only Skill names, so the
+    // repository cards stay out too: they were 47 kB of the payload.
     transform: (feed: TrendingFeedResponse) => ({
-      items: feed.items,
+      textureNames: feed.items.flatMap(repo => repo.skills.map(skill => `${repo.owner}/${repo.repo}/${skill.name}`)),
       board: feedBoardRows(feed).slice(0, HOME_BOARD_ROWS),
     }),
   })),
@@ -110,8 +111,6 @@ const { data: demosData } = useLazyFetch<{ items: HomeDemoItem[] }>('/api/skill-
 const recentUpdates = computed(() => updatesData.value?.items ?? [])
 const recentPublishes = computed(() => publishesData.value?.items ?? [])
 
-const trendingRepos = computed(() => trendingData.value?.items ?? [])
-
 /** Owners whose avatar failed, which means the GitHub account is gone; see `/skills/trending`. */
 const missingAvatars = ref(new Set<string>())
 function onAvatarError(owner: string) {
@@ -132,9 +131,7 @@ const showTrending = computed(() => (trendingData.value?.board.length ?? 0) >= H
 const weekBoardPath = trendingRangeMeta('week').path
 
 /** Real Skill names from this week's trending repositories, for the hero texture. */
-const heroTextureNames = computed(() =>
-  trendingRepos.value.flatMap(repo => repo.skills.map(skill => `${repo.owner}/${repo.repo}/${skill.name}`)),
-)
+const heroTextureNames = computed(() => trendingData.value?.textureNames ?? [])
 
 /**
  * Track order, measured 2026-09-04 rather than assumed.

docs/adr/0013-artifact-size-limits-and-linked-files.md

@@ -0,0 +1,114 @@
+# ADR-0013: Artifact size limits and linked files
+
+Date: 2026-10-07
+
+Amends [ADR-0005](0005-v3-cli-harness-artifact-delivery.md).
+
+## Context
+
+A public build read every Skill file into memory, then packed a second copy as the archive.
+Its limits were 10 MiB an Artifact, 2 MiB a file, and 900 files.
+Only the 900 had a recorded reason: one blob read per file, against 1,000 subrequests.
+
+#487 kept Skills over those limits running by leaving files out.
+`latent-spaces/brag` then ran without the four music files its films use.
+`oaustegard/claude-skills/tree-sitting` ran without eight of its parsers.
+
+Each limit now names the constraint that sets it, measured on 2026-10-07.
+
+## Constraints
+
+| Constraint | Real limit | Old limit | New limit |
+|---|---|---|---|
+| Worker memory | 128 MB per isolate, shared with site requests | 10 MiB of files plus their 10 MiB archive, held at once | None from size. A build holds one network chunk, one inflate write of at most 16 KiB, SKILL.md, and the archive when it is at most 16 MiB |
+| Worker CPU | 300 s for the queue consumer | Not measured | 1 GiB of archive per pass. Inflating and walking costs 4 to 5 ms per MiB, so about 5 s |
+| Wall time | 15 min for the consumer. The skilld CLI waits 60 s for one Resolution | Not measured | A pass stops after the last Skill file. Cold codeload served PostHog/posthog (191 MiB gzipped) in 26 s |
+| Subrequests | 1,000 per invocation | 900 files, one blob read each | No file limit. One or two archive reads, and at most 400 single-file reads for files the archive lacks |
+| R2 put | 5 GiB in one part | Bytes in memory | A stream of known length in one part. R2 checks it against the SHA-256 the scan found |
+| D1 row | 2,000,000 bytes | Not measured | A file list of 448 KiB. The Resolution row holds about 3.34 statements plus the check results |
+| Signer | 128 MB per isolate | 10 MiB, read whole | 64 MiB, hashed as it streams |
+| skilld CLI 3.0 to 3.6.2 | 64 MiB download, 2,000 files, 6 MiB statement. Before 3.6.2 a download gets 30 s, so 64 MiB needs 2.2 MB/s | 10 MiB, 900 files | 64 MiB and 2,000 files. These two now bind |
+| USTAR | A path of at most 256 bytes | Checked after packing | Refused before any byte is read |
+| [GitHub](https://github.com) | 100 MiB a file | Not applicable | Linked files of at most 256 MiB in all |
+
+A private build keeps 10 MiB, 2 MiB a file, and 900 files.
+It still reads one blob per request and encrypts the archive in memory.
+
+## Decision
+
+### A build streams the Repository archive
+
+A public build reads `https://codeload.github.com/{owner}/{repository}/tar.gz/{commit}`.
+That is one subrequest and spends no REST quota.
+It inflates the archive in 16 KiB writes and keeps only the Skill folder's entries.
+It stops reading after the last Skill file.
+
+The Git tree still names every file, its mode, its size, and its blob SHA.
+Each file's bytes are hashed as they pass and must match that blob SHA.
+The archive is only a byte source, as before.
+
+A file the archive lacks, or holds with another size, is read from `raw.githubusercontent.com` at the same commit.
+Git LFS pointers, `export-ignore`, and `export-subst` produce those cases.
+A file whose archive bytes keep their size and fail the digest is read the same way on a second pass.
+
+Artifact order is the UTF-8 byte order of paths.
+It is the order a Git archive lists a tree in.
+All 487 archives of the 2026-10-07 sweep listed their files in that order.
+
+The first pass learns the archive digest and size, the file inventory, and the check results.
+An archive of at most 16 MiB stays in memory, and R2 stores it from there.
+A larger one is read from GitHub a second time and streams into R2 under the digest from the first pass.
+R2 refuses the put if one byte differs.
+The store happens before the checks are recorded.
+The CLI gives each stage after the checks 15 seconds.
+
+### Limits
+
+A public Artifact holds at most 64 MiB and 2,000 files.
+A file has no limit of its own.
+
+When the files exceed a limit, the largest leave the archive first.
+For a CLI without linked files, only files the Skill does not read leave, and the `omitted-files` check lists them.
+That is the #487 rule at the new limits.
+More files than 2,000 leave the same way, so linked files do not change the file count.
+
+### Linked files
+
+A skilld CLI that sends `Skilld-Capabilities: linked-files` on `POST /api/v1/resolutions` may get linked files.
+The Resolution stores that as `linked_files`, and the request fingerprint names it.
+
+When the archive would pass 64 MiB, the largest files other than SKILL.md become linked files, up to 256 MiB.
+The signed statement lists each one:
+
+```json
+{
+  "linkedFiles": [
+    { "path": "scripts/KimiXlsx", "mode": 420, "size": 77001601, "gitBlobSha": "<40 hex characters>" }
+  ]
+}
+```
+
+The CLI verifies the attestation first.
+It then reads each linked file from `https://raw.githubusercontent.com/{owner}/{repository}/{commitSha}/{skillPath}/{path}`, each path segment percent-encoded.
+It refuses the Skill unless every file has the declared size and Git blob SHA.
+It installs the file with the declared mode, beside the archive's files.
+The bytes never pass through skilld.dev, and the signature still covers them through the blob SHA.
+
+The field is present only when it is not empty.
+A CLI without linked files never receives it, because it refuses a statement field it does not know.
+A build with linked files serves only a CLI that reads them.
+A build that left nothing out serves both kinds.
+
+## Consequences
+
+`latent-spaces/brag` runs with its music: 289 files, 16.03 MiB, nothing left out.
+`tt-a1i/archify` runs whole at 10.36 MiB.
+`thedivergentai/gd-agentic-skills/godot-master` runs with 1,728 files.
+`thvroyal/kimi-skills/kimi-xlsx` runs its 73 MiB binary as a linked file for a CLI that reads one.
+
+A first run of a Skill late in a large archive can take longer than the CLI's 60-second wait.
+The build still finishes, and the next run reuses it.
+
+The previous policy `2026-10-07.2` stays signable. This change closes no safety gap.
+A ready build under that policy that left nothing out packs the same files, so it is checked again from its bytes.
+A stored archive over 16 MiB is never read back whole. It loads from GitHub.

docs/adr/0014-symbolic-links-in-a-skill-folder.md

@@ -0,0 +1,101 @@
+# ADR-0014: Symbolic links in a Skill folder
+
+Date: 2026-10-07
+
+Amends [ADR-0013](0013-artifact-size-limits-and-linked-files.md).
+
+## Context
+
+A build refused every Skill folder that held a symbolic link, with `INVALID_SOURCE: The Skill source layout was rejected.`
+The 2026-10-07 sweep found 108 such Skills, the largest class still refused.
+
+- 103 are `simota/agent-skills/*`. Each Skill folder links the shared `_common` folder at the Repository root, and some link `_templates` too.
+- `austintgriffith/ethskills` links `AGENTS.md`, `CLAUDE.md`, and `llms.txt` to `SKILL.md`.
+- `garrytan/gstack` links `connect-chrome` to `open-gstack-browser`.
+- The two `twostraws` Skills link `skills/<name>/references` to the Skill's own `references`.
+- `oaustegard/claude-skills/agent-routing` links `agent-routing` to `../../agent-routing`, outside the Repository.
+
+`tar --dereference` cannot pack simota/agent-skills.
+`_common` links every Skill folder back, so tar recursed 5,800 folders deep and crashed.
+
+## Decision
+
+A build follows each symbolic link in the Skill folder at the same commit.
+The skilld CLI receives regular files, so the attestation, the Resolution answer, and the CLI are unchanged.
+
+### Resolution
+
+The link blob holds a path. The build reads it through the REST API and checks it against the blob SHA.
+It resolves the path from the link's own folder by POSIX rules: `..` leaves the folder, and a link on the way resolves in turn.
+
+- A file becomes one file at the link path.
+- A folder becomes every file in it, under the link path.
+
+Each file keeps its own Git blob SHA from the tree, so the build checks its bytes like any other file.
+The files count against the limits of ADR-0013. A file a link put in the Skill is never a linked file: [GitHub](https://github.com) serves no file at the link path.
+
+### Refused
+
+These links refuse the Skill, with the existing summary and one finding each:
+
+| Link | Finding |
+|---|---|
+| An absolute path | `the target is an absolute path` |
+| `..` past the Repository root | `the target is outside the Repository` |
+| A path through `.git` | `the target is inside .git` |
+| A path that does not exist at the commit | `the target does not exist at this commit` |
+| A path into a Git submodule | `the target is in a Git submodule` |
+| A chain that comes back to a link it passed | `the link loops` |
+| A chain through more than 8 links | `the target passes through more than 8 links` |
+| A folder above the Skill folder that holds it | `the target folder holds the Skill folder` |
+| A blob that is not a UTF-8 path of at most 4,096 bytes | `the link does not hold a valid path` |
+
+A Skill folder may hold 64 links, and following them may cost 128 GitHub reads.
+
+### Left out
+
+Two kinds of link are left out. Following them would repeat the same files without end.
+
+- A link inside a folder that a link names. The build does not read it.
+- A link to a folder inside the Skill that holds the link, such as `atlas/reference/atlas -> ../../atlas`. The Skill already packs every file in it.
+
+Refusing the second kind would keep 22 of the 103 simota Skills refused.
+
+### The check result
+
+The `symbolic-links` check is not required, so a released CLI accepts it.
+It warns when the Skill folder holds a link, and lists each one: `_common -> ../_common` when followed, or the link and the reason when left out.
+A stored build that followed a link is not checked again from its bytes, because the bytes do not show which files a link put there.
+
+### The archive
+
+The bytes of a file a link put in the Skill sit at the target path in the Repository archive, not at the link path.
+So the archive no longer lists every file in Artifact order.
+
+- An entry that passes before its turn stays in memory, up to 8 MiB in one pass.
+- A file whose target comes later waits for it, when the files it holds back fit in that memory.
+- Any other file reads its bytes from `raw.githubusercontent.com` at the target path.
+
+A Skill without links streams as before and holds nothing.
+
+### Private builds
+
+A private build follows links by the same rules. It reads one blob per file, so the reads the links cost come out of its 900-file limit.
+
+## Consequences
+
+A sweep built the 108 Skills with this change on 2026-10-07:
+
+| | Before | After |
+|---|---|---|
+| Ready | 0 | 107 |
+| Refused | 108 | 1, `oaustegard/claude-skills/agent-routing`, whose only link leaves the Repository |
+| Files read from `raw.githubusercontent.com` | | 2, both in `garrytan/gstack` |
+| Slowest build | | 1.1 s |
+| Most memory one build added | | 11.5 MiB, `garrytan/gstack` |
+
+The policy is `2026-10-07.4`. The previous policy `2026-10-07.3` stays signable, because it refused every link.
+A ready build under it held no link, so it is checked again from its bytes.
+
+The skilld CLI reads an installed copy back as a local Skill on `skilld update`, and refuses one of more than 512 files.
+`simota/agent-skills/hone` packs 527 files and `garrytan/gstack` 2,000. A run is not affected.