# Decisions

Append-only. Never edit or delete an entry — supersede it with a new one that links back.
One entry per decision a future maintainer would otherwise have to reverse-engineer.
No index: `grep -n '^## ' docs/DECISIONS.md` lists every entry (date, title, line number).

## 2026-10-30 — Release 1 is homelab-ready, without the community-node compatibility layer
**Status:** accepted
**Context:** Reimplementing n8n's node-facing interface is the project's highest legal-risk area.
**Decision:** Release 1 targets single-box homelab installs (spec §10). The n8n importer ships as
best effort with clear warnings; the community-node layer ships only after legal review.
**Alternatives:** Waiting for legal review before any release (delays everything).
**Consequences:** Imported workflows that use community nodes get placeholders until Release 3.

## 2026-10-30 — AI agents may build every area, behind mandatory guards
**Status:** accepted
**Context:** The project is built mainly by AI agents, whose training data likely includes the
public source of the products being superseded.
**Decision:** Allowed, with CI similarity scanning, per-PR provenance notes, a dependency denylist,
agent tooling restrictions and human sign-off on importer/compat work (spec §3.2 rule 5a).
**Alternatives:** Human-only implementation of high-risk areas (not staffable).
**Consequences:** CI must carry the similarity and denylist guards before high-risk work starts.

## 2026-10-29 — License AGPL-3.0-or-later with a CLA
**Status:** accepted
**Context:** Owner wants the project to stay open while retaining copyright and relicensing freedom.
**Decision:** AGPL-3.0-or-later for everything; outside contributions require a CLA.
**Alternatives:** MIT (allows closed forks); GPL-3.0 (hosted-modification gap); DCO only (no relicensing rights).
**Consequences:** Only AGPL-compatible dependencies; CLA tooling needed before accepting outside PRs.

## 2026-10-29 — Bun-native stack, React editor, Better Auth
**Status:** accepted
**Context:** n8n community nodes are TypeScript/npm packages; owner wants Bun + TypeScript.
**Decision:** Bun with `Bun.serve()` and Bun built-ins (per `bun init` conventions); React + React
Flow + shadcn/ui + Tailwind via Bun HTML imports; Better Auth for authentication, with Passport as
fallback if its SAML/SCIM support proves immature.
**Alternatives:** Next.js (redundant server, public-site oriented); Vite and Hono (superseded by Bun
built-ins); Passport first (Express-centric).
**Consequences:** Verify Better Auth on Bun before building auth (spec §12).

## 2026-10-29 — Adopt AGENTS.md as single source of truth
**Status:** accepted
**Context:** Agents had no durable project context and no consistent workflow between sessions.
**Decision:** `AGENTS.md` is canonical; `CLAUDE.md`/`GEMINI.md` are pointers. Specs are permanent in
`docs/specs/`. Plans live in `docs/plans/` only while work is in progress and are removed before the
merge request. Both override the superpowers default paths.
**Alternatives:** Per-tool rule files (drift, synchronisation debt); no rules file (agents re-explore
the repo every session — measurably slower and more tokens).
**Consequences:** Rule changes happen in one file; pointer files must stay thin. Plans are working
artefacts: kept after merge they go stale and contradict the code, so the spec is the record.