astro-knots — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited astro-knots (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
A vision-mission masquerading as a stack: use the Internet as it was originally, idealistically intended.
Astro Knots is The Lossless Group's umbrella for a family of conventions across ~10+ Astro sites at various stages, built around Astro + Extended Markdown + SCM workflows + APIs. Think JAMstack with a steeper opinion gradient — and no one's heard of it yet.
Reference site: <https://www.lossless.group/projects/gallery/astro-knots>
lossless-monorepo or a sibling repocontext-v/ framework is one such contribution; LFM is another.If a proposal contradicts these, push back before implementing.
A strict preference order. Always reach for the lowest level that works.
@supports, native nesting). If HTML+CSS can do it, do not reach higher.Fewer dependencies is always better. Dependencies are liabilities, not assets.
| Framework | When to use | Why approved |
|---|---|---|
| Astro | Default site framework | Server-first, ships zero JS by default, partial hydration on demand |
| Svelte | Interactivity that genuinely benefits from reactivity / SSR | Compiles to small vanilla JS; no virtual DOM tax |
| GSAP | Animations that exceed CSS animations / transitions | Battle-tested; only when CSS truly can't |
| Reveal.js | One of three presentation-as-code renderings | Plain-HTML slides authored as Markdown |
Two other presentation renderings exist alongside Reveal. // TBD: confirm which (likely Marp and/or Slidev). Update this table when confirmed.
We will test new tools but stay skeptical. Anything not in the approved list is on probation by default.
These are not vetoes-with-exceptions. They are no.
.astro syntax; use it)If a third-party tool requires React/JSX/Angular as a runtime dep, find another tool or build the slice we need. If the user explicitly asks for React, push back and offer the equivalent in approved tech. Only proceed if they confirm with full understanding.
If a site uses output: "server" plus a middleware-based auth gate (Astro's src/middleware.ts checking a session cookie, a token, an Astro.locals role, anything), every route the gate is supposed to protect must declare `export const prerender = false`. Period. No exceptions.
Why this is load-bearing:
In output: "server" mode, a route opts out of server-rendering with export const prerender = true — Astro bakes the route's output into static HTML at build time, and the hosting platform (Vercel, Netlify, GitHub Pages, etc.) serves that HTML straight from its CDN edge. Middleware runs only on requests served by the SSR runtime. Static files served by the CDN go around the runtime entirely:
USER → CDN → static /play/variant/v2.html ← middleware NEVER runs
← auth gate is invisible
← anyone with the URL gets invs. the server-rendered version:
USER → CDN → SSR function → middleware → /play/variant/[variant].astro render
← auth gate ALWAYS runsThe dev-mode symptom is sneakier than the production hole: prerendered routes in dev with output: "server" do run through middleware, but the request context Astro hands to that middleware doesn't surface the inbound `Cookie` header reliably. The middleware reads cookies.get("session") → undefined → bounces to /access, even though the browser is correctly sending the cookie. Operators see a "login works once, then loops" symptom that looks like a cookie bug. It's a prerender bug.
The rule:
| Route is... | prerender must be |
|---|---|
In the middleware's public allowlist (/changelog, /access, public-facing marketing pages, etc.) | true is fine — middleware passes through anyway |
| Under the gate (any path the middleware protects) | `false`. Always. |
| Unsure | false and prove the case for true later |
When sweeping an existing site, grep every export const prerender = true and cross-reference against the middleware's PUBLIC_PREFIXES / equivalent. Anything prerendered AND gated is a silent production bypass. Fix immediately; this is not a polish-pass concern.
Realized example: calmstorm-decks shipped /play/variant/[variant].astro and /play/section/[slot].astro as prerender = true with a getStaticPaths() enumerating variants. The dev symptom was an unbreakable auth loop ("submit code, land on a page once, then every navigation bounces"). The production exposure was that anyone with the URL could play the deck. Fix: flip both to prerender = false, then restart the dev server (Astro doesn't HMR the prerender flag). See dididecks-ai/changelog/2026-05-17_02.md for the full debugging trace and the helper-pattern hardening that came out of it.
Our first true package. Polyglot but lean: extended markdown syntax → component render pipeline. More daring than CommonMark, less rigid than MDX. Any syntax can be added as a trigger to render a component.
A dedicated lfm skill is forthcoming. Until it lands:
.md files for Astro Knots sitesOur coined term — see references/pseudomonorepos.md. Brief: a parent repo that adds child repos as git submodules, primarily so the parent can host a context-v/ that aggregates context across the children. Not a true monorepo (no shared build, no shared deps), not loosely coupled either.
Implication: when working in a child repo, also check the parent's context-v/ for relevant blueprints/specs. Headaches in implementation often have answers in the parent.
A dedicated pseudomonorepos skill exists — load it whenever working in this tree. It encodes the search-first discipline that composes with everything else.
When the user asks for X, default behavior:
| Ask | Default response |
|---|---|
| "Add React" / "use React" | Push back. Offer Astro + Svelte equivalent. |
| "Use MDX" | Push back. Offer LFM-shaped approach. |
| "Install [framework]" | Check Tech Hierarchy. If not approved, ask why and propose alternative. |
| "Add a UI library" | Strong skepticism. Most often: write the component in Astro/Svelte. |
| "Animate this" | CSS first. GSAP only if CSS genuinely can't do it. |
| "Make it interactive" | Vanilla JS or Svelte. Justify before reaching higher. |
| "Build a slide deck" | Markdown + Reveal (or one of the other two). |
| "Document this work" | Use context-v/ per the context-vigilance skill. |
"Add prerender = true to a route" | If the site uses output: "server" + middleware auth, refuse unless the route is in the middleware's public allowlist. See "Auth-gated routes must not be prerendered" above. |
These apply to every YAML-bearing file in an Astro Knots site or its context-v/ — content collections, specs, prompts, blueprints, reminders, changelogs, deck slides, everything.
Any string value that's longer than a few words — descriptions, ledes, titles with punctuation, URLs that contain query strings or fragments, error messages, prompts — wraps in double quotes (").
# Do
title: "Secure Document Sharing — #1 DocSend Alternative"
description: "An open-source document and data-rooms sharing platform. Free alternative to DocSend with custom branding."
og_image: "https://www.papermark.com/_static/meta-image.png?v=2&utm=share"
lede: "A safe, non-judgemental support session — nobody here knows what they're doing either."
# Don't (works until it doesn't)
title: Secure Document Sharing — #1 DocSend Alternative # `#` starts a YAML comment → silent truncation
description: An open-source platform: free alternative. # `:` mid-string can break parsing
og_image: https://example.com/img.png?a=1&b=2 # `&` is a YAML anchor sigilWhy: long human-authored strings reliably contain at least one of : # & * > | ! % @ ` , [ ] { } — every one of which has special YAML meaning unquoted. Wrapping in "` makes the value a literal string and removes the entire class of "works locally, breaks in CI" bugs. Cheap to do, expensive to debug.
We never use a strict YAML parser for content frontmatter. The expected behavior is property-level recovery: drop bad keys, keep the document, surface a precise warning, escalate only for load-bearing keys. See [[YAML-Frontmatter-Parsing-Must-Be-Lenient]] in any site's context-v/reminders/ (or in astro-knots/context-v/reminders/) for the pattern. Strict parsers turn one author typo into a site-wide outage and are not acceptable in this stack.
snake_case. Tags are Train-Case.Already covered in the context-vigilance skill, restated here because it's the same surface: property names use snake_case (Obsidian renders them that way), tag values use Train-Case. Never camelCase keys, never lowercase tags.
A new Astro-Knots site (or package, or study) gets initiated through a spec, not by jumping straight into pnpm create astro. The how of developing that spec is generic and lives in the context-vigilance skill — specifically references/developing-a-spec.md. Load that reference whenever the user wants to initiate a new project.
Before writing any spec stub:
pseudomonorepos skill. If yes, the new spec almost certainly belongs in the parent's context-v/specs/, not in a not-yet-created child's. Confirm with the user.context-v/specs/ (frontmatter + H1 only), then return focus to discussion. Don't try to draft the spec body in advance of the conversation.After spec sign-off, before implementation: load the setup playbook at references/playbooks/new-site-setup.md — the 12-step flow from repo creation through deploy config. For executable commands and file templates, cross-reference astro-knots/context-v/prompts/New-Site-Quickstart-Guide.md in the monorepo.
Deploying to GitHub Pages instead of Vercel (for splash pages, per-repo landing sites, free static hosts): load references/playbooks/github-pages-deploy.md. It captures the canonical workflow shape, the astro.config.mjs base setting, and the three setup-time gotchas every new GitHub Pages repo hits — Pages-not-provisioned (enablement: true), branch-not-allowed (environment protection rule), and Source-still-on-"Deploy from a branch". Pay the setup tax once per repo, then the workflow handles itself.
Adding share-card metadata (OpenGraph / Twitter / canonical / robots): load references/playbooks/opengraph-system.md. It encodes the realized two-file pattern shipped in calmstorm-decks and reach-edu-hub — src/lib/seo.ts registry + src/components/basics/MetaTags.astro renderer — plus the gated-vs-public and local-vs-CDN policy axes that drive defaults. Source blueprint: lossless-monorepo/content/lost-in-public/blueprints/Maintain-an-Elegant-Open-Graph-System.md.
Making the site LLM-friendly at inference time (public docs, blueprints, study profiles, anything an external LLM might want to use to answer a user's question): load references/playbooks/llms-txt-and-md-sidecars.md. Two artifacts: public/llms.txt (curated index) and a [...slug].md.ts endpoint per content collection (raw markdown sidecar at the same URL with .md appended). Astro doesn't auto-generate either the way nbdev / VitePress / Docusaurus do — fill the gap deliberately. Skip on gated/noindex sites. Source profile: studies/open-specs-and-standards/context-v/profiles/Profile__llms-txt.md.
context-v/blueprints/ should reflect Astro Knots tech principles.references/philosophy.md — the vision in depth, build-in-public practicereferences/tech-stack.md — full rationale for each approved/prohibited techreferences/ecosystem.md — the family of sites, LFM, pseudomonorepos, roadmapreferences/playbooks/new-site-setup.md — the 12-step new-site flow (default-Vercel deploy)references/playbooks/github-pages-deploy.md — workflow shape, astro.config.mjs base, and the three setup-time gotchas every new GitHub Pages repo hitsreferences/playbooks/opengraph-system.md — the seo.ts + MetaTags.astro pattern for share-card metadata (OG, Twitter, canonical, robots), with gated-vs-public and local-vs-CDN policy axesreferences/playbooks/llms-txt-and-md-sidecars.md — /llms.txt + .md sidecar route pattern for making public Astro sites LLM-friendly at inference time~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.