# Make a little link relay of your own

Each short link is a native Spacefast redirect rule.
The default build has no link database and no application link API.
Create through the owner’s authorized connection → read the saved rule → verify its HTTP status and Location.

## Start with the clean source

Download the starter ZIP linked from /learn, extract it into a new directory, and run `npm ci`. The placeholder identity is Link Relay throughout the config and capsule. No original owner redirect records, account binding, verification tokens or visitor records are included. The supplied social image is a JPEG at `assets/versioned/social-v2.jpg`; replace the reference artwork and baked lettering for your own identity before release.

Run `npx tsc --noEmit` and `node --test scripts/*.test.mjs`. Dependencies are pinned to native Zero0.4.1. Preserve browser-mode pages, the native capsule and compiler. The authored home.html and learn-shell.html wrappers provide route-specific initial metadata and readable static fallbacks around the same browser runtime. They do not migrate the app to server rendering.

Create a local remix.json with your name, byline and actual HTTPS origin:

```json
{"name":"My Link Relay","byline":"a little thing by me","origin":"https://your-domain.example","articleUrl":""}
```

Run `node scripts/configure.mjs remix.json`. This updates local identity, capsule, both HTML wrappers, robots and sitemap. Configure before selecting the optional counter. Never deploy the example.invalid placeholder URLs. Regenerate your own clean teaching downloads and adapt the resource map before publication. The source files and artwork remain editable. Changing semantic copy does not reletter an image; update desktop and phone lettering together.

The versioned asset folder uses one cache rule, `/assets/versioned/*`, for immutable public assets. Give a changed asset a new versioned filename. Keep private exports and owner records outside public files and packages.

For local native preview use `sf dev --port 4196 --state-backend sqlite --no-watch`. If this installed compiler omits author-static assets, the loopback-only scripts/dev-assets.mjs adapter serves assets on4197 and forwards native requests to4196. Never share private local capability URLs.

## Add a link through your existing connection

Read references/links-and-tracking.md. Resolve the new owner’s team and Space using their authenticated Spacefast connection. Read the entire current config, settingsDigest, verified liveUrl and authored route inventory. The readable planner validates destinations, aliases and collisions while preserving the complete settings overlay.

```json
{"action":"create","prefix":"/","alias":"x","destination":"https://x.com/your-account","status":302}
```

Pass snapshot.json and request.json to `node scripts/redirect-plan.mjs snapshot.json request.json link.svg`. Root aliases use prefix `/`; the default is `/r/`. Choose302 for editable links or301 for permanent links. Browsers may cache301 destinations, so later edits may not reach every previous visitor immediately. Each create/edit plan includes a locally generated QR SVG for the short URL.

Send only the returned `spaceId` and `body` to the authenticated settings update operation. `artifacts` contains local URL/QR output and is not an API argument. Use the observed baseSettingsDigest; never force a stale write. Read the saved settings and anonymously request the exact short URL with redirects disabled. Return it only when status and Location match. Anonymous visitors and public browser tools never receive link-writing permission.

## Protect links across deployments

Before every publish, read a fresh complete owner Space snapshot through the existing connection and save it privately with its id, config, settingsDigest and `liveUrl` containing the HTTPS public origin. Do not put it in a release folder or download. Capture and verify every literal native redirect, including root aliases:

```sh
node scripts/link-guard.mjs capture .private/space.json .private/links.json
# Publish the new version using the authorized native workflow.
node scripts/link-guard.mjs verify .private/links.json .private/verification.json
```

For a CLI deployment the guard can wrap the command and perform both checks automatically:

```sh
node scripts/link-guard.mjs deploy .private/space.json .private/links.json -- sf publish ./release --space YOUR_SPACE --json
```

The guard exports each rule, verifies the pre-deploy baseline, then compares actual HTTP status and Location after publishing. It checks even if the publish command fails. Missing or changed links produce a nonzero exit and a private diff; do not call that release successful. Prefer publishing a preview and promoting its exact reviewed version where the provider supports it.

If a publish drops records, read another fresh complete snapshot, then run `node scripts/link-guard.mjs restore-plan .private/links.json .private/fresh-space.json`. Apply its guarded plan through the existing owner connection and required provider approval. It restores only missing rules, preserves other fresh settings and refuses conflicts with changed records. Re-run verify afterward. No API key or automatic force-write is required.

## Counts, discovery and release checks

Default analytics/log aggregates are approximate and may omit paths. An optional native database-backed request counter is supplied in optional/counter; it is disabled by default. See its README for explicit setup and authenticated reads. Count processed GET requests, including bots and repeats, rather than promising unique people.

Inspect actual desktop, intermediate,390px and320px pages, keyboard controls, reduced motion, image loading and horizontal overflow. Shortfolk has no fixed hosting banner or Text view button. Keep its footer credit in the artwork; do not add a separate bottom banner.

Verify anonymous initial HTML has the correct route-specific title, description, canonical, social URL and one Twitter card. Verify the initial /learn body contains a useful summary and absolute recipe, skill, llms.txt and both ZIP links with JavaScript disabled. Check every link, JPEG content type, robots and sitemap on the exact live destination. Crawling permission and submission do not prove indexing or AI recommendations.

Read references/discovery.md for the public AI resource map. Visitors give their own AI the site link; no copied prompt or automatic skill installation is needed. Public read-only browser tools teach independent builds and never grant access to the original owner’s links or private analytics.

## Primary references

- Native Zero: https://spacefast.com/docs/zero/
- Routing: https://spacefast.com/docs/routing/
- CLI: https://spacefast.com/docs/cli/
- Agent Skills format: https://agentskills.io/specification
