Add repo memory layer and plans

Co-Authored-By: Claude Fable 5 <[email protected]>

.agents/MEMORY.md

@@ -0,0 +1,33 @@
+# Repo Memory
+
+Curated, reviewed knowledge for coding agents working in this repository.
+Memory is an accelerator, not a second source of truth.
+
+## Precedence (highest first)
+
+1. Source code and tests
+2. Executable configuration
+3. Accepted design records / docs
+4. `AGENTS.md`
+5. This memory
+
+If memory conflicts with anything above it, the memory is stale — propose a fix.
+
+## Topics
+
+- `memory/architecture.md` — durable architectural decisions and constraints
+- `memory/conventions.md` — validated conventions not obvious from the code
+- `memory/lessons.md` — hard-won lessons and recurring landmines
+- `memory/decisions.jsonl` — structured decision records (one JSON object per line)
+
+## Write policy
+
+Agents MAY read everything here and MAY add candidates under `proposals/`
+(one file per proposal, named `YYYY-MM-DD-<slug>.md`, with evidence links).
+Agents MUST NOT edit `memory/` directly; trusted memory changes only through
+reviewed commits that promote a proposal.
+
+## Prohibited content
+
+Credentials or secrets, personal data, raw transcripts or tool logs, session
+TODOs, high-frequency agent state, unverified external claims.

.agents/memory/architecture.md

@@ -0,0 +1,5 @@
+# Architecture
+
+Durable architectural decisions and constraints for Artstr Studio.
+
+No entries yet.

.agents/memory/conventions.md

@@ -0,0 +1,5 @@
+# Conventions
+
+Validated conventions not obvious from the code.
+
+No entries yet.

.agents/memory/decisions.jsonl

@@ -0,0 +1 @@
+{"kind":"lesson","subject":"codebase/single-file-editing","summary":"The entire app lives in src/index.html (~42k lines, no build, no npm), so edits must be surgical and tightly scoped; the only automated suite is node --test \"tests/premium/*.test.mjs\" (quoted glob form required), covering src/premium2-helpers.mjs — everything else is validated manually in a browser.","status":"active","evidence":[{"type":"repository","ref":"src/index.html"},{"type":"test","ref":"tests/premium"},{"type":"repository","ref":"AGENTS.md"}],"created":"2026-08-12","supersedes":[]}

.agents/memory/lessons.md

@@ -0,0 +1,22 @@
+# Lessons
+
+Hard-won lessons and recurring landmines.
+
+## The whole app is one ~42k-line file — edit surgically, test what you can
+
+Nearly every change lands in `src/index.html` (~42k lines): logic, styles,
+and inline encoders all live there by design, with no build step and no
+package.json. Tight scoping matters — locate the exact function or block and
+keep the diff minimal, because a sloppy edit in a file this size is hard to
+review and easy to break silently. The only automated coverage is
+`node --test "tests/premium/*.test.mjs"` (Node 22; the quoted glob form is
+required so the pattern reaches node's test runner intact), which covers
+`src/premium2-helpers.mjs` and the premium/NWC flows. Everything else is
+validated manually by opening `src/index.html` in a browser and exercising
+the affected feature.
+
+Authoritative source:
+- src/index.html
+- tests/premium/ (fixtures in tests/fixtures/)
+- src/premium2-helpers.mjs
+- AGENTS.md ("Build / test / validate", "Change policy")

.agents/plans/README.md

@@ -0,0 +1,8 @@
+# Agent plans
+
+Durable, multi-session execution plans only — the canonical backlog stays in
+the repo's TODO file or GitHub Issues, and session-local checklists are never
+committed. One plan per task, named `<ticket-or-slug>.md`, in `active/`;
+move finished plans to `archive/`. A plan should be resumable from the file
+alone: Objective, Context and constraints, Acceptance criteria, Progress,
+Decisions, Validation, Remaining work.

.agents/proposals/README.md

@@ -0,0 +1,7 @@
+# Memory proposals
+
+Agents: drop candidate memories here, one file per proposal, named
+`YYYY-MM-DD-<slug>.md`. State the claim, the evidence (file paths, commits,
+test results), and why it is durable. A human reviews and either promotes it
+into `../memory/` in a reviewed commit or deletes it. Nothing in this
+directory is trusted context.