rastrillo / idear Public

docs: fetch SKILL.md from the module cache, not a dead amadan.net URL

amadan.net serves files only through an HTML viewer page
(?ref=main&path=SKILL.md) — every raw-content variant 404s or returns
HTML, so the curl instruction in README.md never worked. After `go get`
the doc is already on disk, pinned to whatever version the app actually
resolved: `cat "$(go list -m -f '{{.Dir}}' amadan.net/rastrillo/idear)/SKILL.md"`.
Corrects the same claim in the design spec, which described the
now-abandoned stable-URL plan.

Paul Campbell pushed by paul@keymail.dev 3 weeks ago 31faf7a94f89a6ff964ebb670609cf428afbf087 parent 8818096

2 files changed, +18 −12

README.md +4 −2
docs/superpowers/specs/2026-08-23-idear-design.md +14 −10

diff --git a/README.md b/README.md

index 949acb3..8f60bc9 100644

--- a/README.md

+++ b/README.md

@@ -32,10 +32,12 @@ way `password.Config.RenderSignin` does.

**[`SKILL.md`](SKILL.md)** is the authoring doc — read it instead of the

source. It carries the wiring, the route table, the two identity adapters,

the security discipline, and the traps that are silent when you get them

-wrong. An agent can fetch it directly:

+wrong. Once `go get` has fetched the module, it's already on disk: an

+agent can read it straight out of the module cache, pinned to the exact

+version the app resolved (no URL to drift from the code it documents):

```sh

-curl -s https://amadan.net/rastrillo/idear/SKILL.md

+cat "$(go list -m -f '{{.Dir}}' amadan.net/rastrillo/idear)/SKILL.md"

```

**[`example/`](example/)** is a complete working app on rastrillo + idear,

diff --git a/docs/superpowers/specs/2026-08-23-idear-design.md b/docs/superpowers/specs/2026-08-23-idear-design.md

index 9bbfb2f..5f13a05 100644

--- a/docs/superpowers/specs/2026-08-23-idear-design.md

+++ b/docs/superpowers/specs/2026-08-23-idear-design.md

@@ -430,13 +430,17 @@ it does not come for free the way the framework's does. Rastrillo's

land in a versioned module-cache directory nobody names, and

`docs/addons` is a directory page, not a skill.

-So idear's `SKILL.md` is **served at a stable URL**,

-`https://amadan.net/rastrillo/idear/SKILL.md`, and `docs/site/addons.md`

-carries the exact `curl` line for it — matching the convention Rastrillo's

-own `SKILL.md` already uses for `curl -s

-https://rastrillo.org/docs/<page>.md`. No new machinery, and it

-generalises to every future addon: the directory page's job is to hand an

-agent a fetchable skill, not to describe one.

+So idear's `SKILL.md` is **fetched out of that module-cache directory**:

+`go list -m -f '{{.Dir}}' amadan.net/rastrillo/idear` names it, pinned to

+whatever version the app actually resolved, and `docs/site/addons.md`

+carries the exact `cat "$(go list -m -f '{{.Dir}}'

+amadan.net/rastrillo/idear)/SKILL.md"` line for it — a one-step fetch in

+the same spirit as Rastrillo's own `SKILL.md` pointing agents at `curl -s

+https://rastrillo.org/docs/<page>.md`, just without a URL to keep serving

+(amadan.net has no raw-file route, only an HTML viewer, so a URL was never

+going to stay a one-step fetch). No new machinery, and it generalises to

+every future addon: the directory page's job is to hand an agent a

+fetchable skill, not to describe one.

An addon whose skill doc an agent cannot find saves an app the typing and

none of the reading — which is the whole cost argument, lost.

@@ -506,9 +510,9 @@ Living in `docs/site/` rather than the website repo means it inherits all

six docsite gates and rides the existing vendoring. The URL is

`rastrillo.org/docs/addons`.

-The addons page also carries the `curl` line for idear's own `SKILL.md`

-(§6) — without it the directory describes a skill instead of delivering

-one.

+The addons page also carries the module-cache `cat` line for idear's own

+`SKILL.md` (§6) — without it the directory describes a skill instead of

+delivering one.

**`SKILL.md`**, roughly 330 bytes into §3 — where the reader has just

been told scoping separates users and not tenants, and immediately