From 23c55177111927a6040524e1daccc3622e946eb1 Mon Sep 17 00:00:00 2001
From: James Manuel <moodyjmz@users.noreply.github.com>
Date: Thu, 23 Jul 2026 16:39:15 +0200
Subject: [PATCH 01/14] docs: add CSS, component-extraction and testability
 guidance for agents

Adds four rules covering what came up while redoing #79/#83 this
session: reuse existing design tokens over hardcoded values, extract
components only for genuine multi-site duplication (as its own
commit unless the component is new to the feature), prefer
@nextcloud/vue over hand-rolled markup, and structure code for
testability without extracting solely to reach a test.

Signed-off-by: James Manuel <moodyjmz@users.noreply.github.com>
---
 AGENTS.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index bbfdb9e..130a000 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -43,3 +43,56 @@ bot recompiles and commits assets via `/compile` on the PR. `.githooks/pre-commi
 blocks this locally as a backstop, but don't rely on the hook catching it —
 run `npm run build` for local testing, then `git restore --staged js css`
 (or don't stage them in the first place) before committing.
+
+## Reuse CSS variables and existing structure
+
+Prefer existing design tokens (`var(--color-...)`, `var(--border-radius)`,
+`var(--default-clickable-area)`, `var(--default-grid-baseline)`, etc.) over
+hardcoded pixel values or colours. Before sizing or styling a new element,
+check how a comparable element elsewhere in `src/` does it, and how the
+`@nextcloud/vue` component it sits next to sizes itself (its compiled CSS is
+under `node_modules/@nextcloud/vue/dist/assets/*.css` — many tokens
+themselves are defined server-side, not in this package, so a grep miss
+there isn't proof no token exists). If you genuinely can't find a matching
+token, use the real value — never invent a `var(--something)` that isn't
+defined anywhere, it silently resolves to nothing.
+
+## Extract components over duplicated template blocks
+
+When the same markup — or near-identical markup differing only in
+props/size — appears at multiple call sites *and* a future change (a bug
+fix, a new prop, a behaviour tweak) would need to be applied at every one
+of them to stay correct, extract it into its own component rather than
+copy-pasting. Two call sites can already justify this for UI markup, where
+divergence is easy to introduce by only fixing one copy. Don't extract for
+a single call site, and don't extract just because two blocks currently
+look similar if that similarity is coincidental rather than a shared
+responsibility — that's premature abstraction, not reuse.
+
+Extraction is a refactor. If you're pulling apart duplication that already
+existed before your change, do that as its own commit, separate from the
+functional change that prompted you to notice it (see "Commit atomically"
+above). If the component is new and only exists because of the feature
+you're building, it belongs in that feature's commit — you're not
+separating pre-existing duplication, you're introducing the abstraction as
+part of the change itself.
+
+## Prefer existing NC/Vue libraries over hand-rolled markup
+
+Check whether `@nextcloud/vue/components` (or another already-installed
+dependency) already covers what you're building before writing raw
+HTML/CSS for it. Hand-rolled UI drifts from the design system over time and
+duplicates maintenance that the library already carries.
+
+## Structure code so it's easily unit-testable
+
+Prefer small, focused functions/components with explicit inputs (props,
+arguments) over logic buried inline in a large `<script setup>` or template,
+which is often reachable only through a full component mount with heavy
+stubbing — see `src/utils/` and `src/components/` for the pattern this repo
+already uses. But don't extract solely to make something testable: if the
+only caller of the new function or component would be its own test, it
+didn't need extracting. Extract when the logic has a real responsibility of
+its own (validation, formatting, a distinct UI piece) that composes into
+the larger component either way — testability is a side effect of that,
+not the reason for it.

From a525cb9d5959d9a617461c900d563d0adabf597a Mon Sep 17 00:00:00 2001
From: James Manuel <moodyjmz@users.noreply.github.com>
Date: Thu, 23 Jul 2026 22:11:18 +0200
Subject: [PATCH 02/14] docs: rewrite agent guidance for concision and
 precision
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Restructures the previous commit's four new sections plus the
existing ones into a tighter set, replacing the "extract only for
2+ call sites" rule with a naming-based test — validateFilename in
this repo is a legitimate single-call-site extraction that the old
call-site-count rule would have wrongly discouraged.

Also fixes a real gap found in review: the pre-PR checklist was
missing npm run stylelint, a separate CI gate from npm run lint.

Signed-off-by: James Manuel <moodyjmz@users.noreply.github.com>
---
 AGENTS.md | 158 +++++++++++++++++++++++-------------------------------
 1 file changed, 68 insertions(+), 90 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 130a000..c389c95 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,98 +1,76 @@
 # Agent instructions
 
-Instructions for AI coding agents (Claude Code and others) working in this repo.
-Human contributors: see `README.md`.
+For AI coding agents. Human contributors: see `README.md`.
 
-## Before starting work
+## Branch from fresh `main`
 
-Sync with `origin/main` before branching and again before opening a PR. Branch
-from a stale base and CI's `npm-build` "Check build changes" job, DCO check, or
-plain merge conflicts will fail for reasons unrelated to your change — and a
-refactor may have moved the code you're about to edit somewhere else entirely.
+```bash
+git fetch origin && git checkout -b <branch> origin/main
+```
+
+A stale base fails CI's `npm-build` "Check build changes" job or DCO, and a
+refactor may have moved the code you're about to edit. You'll re-check `main`
+before opening the PR too — see below.
+
+## One concern per commit, signed off
+
+`git commit -s` — CI enforces DCO. A functional change, a cleanup, and a docs
+update are three commits. Confident AI output still needs splitting: a
+flawless-looking helper and a real bug can come from the same commit.
+
+## Commit source only
+
+The `nextcloud-command` bot compiles assets via `/compile` on the PR. Build
+locally to test, then hand the tree back clean:
 
 ```bash
-git fetch origin
-git checkout -b <branch> origin/main
+npm run build
+git restore --staged js css
 ```
 
-If you've been working for a while, `git fetch origin && git log --oneline
-HEAD..origin/main` before pushing — rebase if `main` has moved.
-
-## Commit atomically
-
-One concern per commit: a functional change, a cleanup, and a docs update are
-three commits, not one. Do not bundle an unrelated fix into a feature commit
-because it happened to be nearby. A reviewer (human or bot) diffing a single
-concern can actually verify it; a "fix + refactor + docs" commit can't be
-reviewed, only trusted.
-
-This applies to AI-authored changes as much as human ones. Confident,
-well-commented AI output still needs to be split and verified per concern —
-a flawless-looking helper and a real bug can come from the same commit.
-
-## Sign off every commit
-
-`git commit -s`. DCO is enforced by CI; a missing `Signed-off-by:` trailer
-fails the PR regardless of how correct the change is.
-
-## Never hand-commit build artifacts
-
-Do not stage or commit changes under `js/` or `css/` — see `README.md`
-("Committing changes") for the full flow. Source only; the `nextcloud-command`
-bot recompiles and commits assets via `/compile` on the PR. `.githooks/pre-commit`
-blocks this locally as a backstop, but don't rely on the hook catching it —
-run `npm run build` for local testing, then `git restore --staged js css`
-(or don't stage them in the first place) before committing.
-
-## Reuse CSS variables and existing structure
-
-Prefer existing design tokens (`var(--color-...)`, `var(--border-radius)`,
-`var(--default-clickable-area)`, `var(--default-grid-baseline)`, etc.) over
-hardcoded pixel values or colours. Before sizing or styling a new element,
-check how a comparable element elsewhere in `src/` does it, and how the
-`@nextcloud/vue` component it sits next to sizes itself (its compiled CSS is
-under `node_modules/@nextcloud/vue/dist/assets/*.css` — many tokens
-themselves are defined server-side, not in this package, so a grep miss
-there isn't proof no token exists). If you genuinely can't find a matching
-token, use the real value — never invent a `var(--something)` that isn't
-defined anywhere, it silently resolves to nothing.
-
-## Extract components over duplicated template blocks
-
-When the same markup — or near-identical markup differing only in
-props/size — appears at multiple call sites *and* a future change (a bug
-fix, a new prop, a behaviour tweak) would need to be applied at every one
-of them to stay correct, extract it into its own component rather than
-copy-pasting. Two call sites can already justify this for UI markup, where
-divergence is easy to introduce by only fixing one copy. Don't extract for
-a single call site, and don't extract just because two blocks currently
-look similar if that similarity is coincidental rather than a shared
-responsibility — that's premature abstraction, not reuse.
-
-Extraction is a refactor. If you're pulling apart duplication that already
-existed before your change, do that as its own commit, separate from the
-functional change that prompted you to notice it (see "Commit atomically"
-above). If the component is new and only exists because of the feature
-you're building, it belongs in that feature's commit — you're not
-separating pre-existing duplication, you're introducing the abstraction as
-part of the change itself.
-
-## Prefer existing NC/Vue libraries over hand-rolled markup
-
-Check whether `@nextcloud/vue/components` (or another already-installed
-dependency) already covers what you're building before writing raw
-HTML/CSS for it. Hand-rolled UI drifts from the design system over time and
-duplicates maintenance that the library already carries.
-
-## Structure code so it's easily unit-testable
-
-Prefer small, focused functions/components with explicit inputs (props,
-arguments) over logic buried inline in a large `<script setup>` or template,
-which is often reachable only through a full component mount with heavy
-stubbing — see `src/utils/` and `src/components/` for the pattern this repo
-already uses. But don't extract solely to make something testable: if the
-only caller of the new function or component would be its own test, it
-didn't need extracting. Extract when the logic has a real responsibility of
-its own (validation, formatting, a distinct UI piece) that composes into
-the larger component either way — testability is a side effect of that,
-not the reason for it.
+`.githooks/pre-commit` catches staged `js/` or `css/` as a second line of
+defence — unstage them yourself and it never has to fire.
+
+## Reuse before you write
+
+Preference order: an existing `@nextcloud/vue` component, an existing design
+token, an existing pattern in `src/`. Each keeps you on the design system that
+the library already maintains.
+
+Tokens: `var(--color-...)`, `var(--border-radius)`,
+`var(--default-clickable-area)`, `var(--default-grid-baseline)`. Treat
+`node_modules/@nextcloud/vue/dist/assets/*.css` as a partial list — many tokens
+are defined server-side, so search there and assume more exist. Where no token
+matches, use the literal value: an undefined `var()` doesn't fall back to
+anything sensible, the declaration is just dropped.
+
+## Separate concerns by default
+
+Give each responsibility its own unit. If you can name what a block of markup
+or logic *does* — validates a filename, formats a timestamp, renders a share
+row — that name is the component or function it should become, at one call site
+or five. Prefer small units with explicit inputs (props, arguments) over logic
+inline in a large `<script setup>`; see `src/utils/` and `src/components/` for
+the shape this repo already uses.
+
+Two things follow:
+
+- **Naming is the test — and the bar is a specific, honest name, not just any
+  name.** Almost any block can be given *some* label; that's not the test.
+  If the only name you can find is generic (`handleStuff`, `MiscWrapper.vue`)
+  **or** merely plausible-sounding without actually describing one clear
+  responsibility, the split is along the wrong seam — find the boundary that
+  earns a real name, or leave it inline until one emerges.
+- **Extraction is its own commit** when you're separating duplication or
+  responsibilities that predate your change. A unit that exists only because of
+  the feature you're building belongs in the feature commit.
+
+## Before opening a PR
+
+```bash
+git fetch origin && git log --oneline HEAD..origin/main   # rebase if non-empty
+npm run lint
+npm run stylelint
+npm run test:unit
+npm run build   # then unstage js/ css/
+```

From 519a9a391745545e78271d07ec82b6a23184590b Mon Sep 17 00:00:00 2001
From: James Manuel <moodyjmz@users.noreply.github.com>
Date: Thu, 23 Jul 2026 22:19:49 +0200
Subject: [PATCH 03/14] docs: tighten agent guidance further

Consolidates the reuse and extraction sections down to their
essential positive rules (name the responsibility; use the design
token or don't invent one) and drops persuasion aimed at a reader
who isn't there. Corrects the var() fallback claim to match the
actual CSS spec behaviour (guaranteed-invalid -> inherited/initial,
not cascade fallback), restores that the bot commits assets (not
just compiles them) and notes /compile needs a human to type it, and
adds the "name needs an 'and'" check as a mechanical extraction test.

Signed-off-by: James Manuel <moodyjmz@users.noreply.github.com>
---
 AGENTS.md | 46 ++++++++++++++++++++++++++--------------------
 1 file changed, 26 insertions(+), 20 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index c389c95..74e855c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -15,52 +15,58 @@ before opening the PR too — see below.
 ## One concern per commit, signed off
 
 `git commit -s` — CI enforces DCO. A functional change, a cleanup, and a docs
-update are three commits. Confident AI output still needs splitting: a
-flawless-looking helper and a real bug can come from the same commit.
+update are three commits.
+
+Confident AI output still needs splitting: a flawless-looking helper and a real
+bug can come from the same commit.
 
 ## Commit source only
 
-The `nextcloud-command` bot compiles assets via `/compile` on the PR. Build
-locally to test, then hand the tree back clean:
+Build locally to test, then hand the tree back clean:
 
 ```bash
 npm run build
 git restore --staged js css
 ```
 
-`.githooks/pre-commit` catches staged `js/` or `css/` as a second line of
-defence — unstage them yourself and it never has to fire.
+`js/` and `css/` are build output; the `nextcloud-command` bot compiles and
+commits them to your branch after someone comments `/compile` on the PR — say in
+the description that it's still needed. `.githooks/pre-commit` is a backstop,
+not a plan.
 
 ## Reuse before you write
 
 Preference order: an existing `@nextcloud/vue` component, an existing design
-token, an existing pattern in `src/`. Each keeps you on the design system that
-the library already maintains.
+token, an existing pattern in `src/`.
+
+Each keeps you on the design system the library already maintains; hand-rolled
+equivalents drift from it and duplicate maintenance.
 
 Tokens: `var(--color-...)`, `var(--border-radius)`,
 `var(--default-clickable-area)`, `var(--default-grid-baseline)`. Treat
 `node_modules/@nextcloud/vue/dist/assets/*.css` as a partial list — many tokens
 are defined server-side, so search there and assume more exist. Where no token
-matches, use the literal value: an undefined `var()` doesn't fall back to
-anything sensible, the declaration is just dropped.
+matches, use the literal value.
+
+An undefined `var()` doesn't fall back to an earlier declaration in the same
+rule — the property resets to its inherited or initial value, so a hardcoded
+line above the token is not a safety net.
 
 ## Separate concerns by default
 
-Give each responsibility its own unit. If you can name what a block of markup
-or logic *does* — validates a filename, formats a timestamp, renders a share
-row — that name is the component or function it should become, at one call site
-or five. Prefer small units with explicit inputs (props, arguments) over logic
+Give each responsibility its own unit. If you can name what a block of markup or
+logic *does* — validates a filename, formats a timestamp, renders a share row —
+that name is the component or function it should become, at one call site or
+five. Prefer small units with explicit inputs (props, arguments) over logic
 inline in a large `<script setup>`; see `src/utils/` and `src/components/` for
 the shape this repo already uses.
 
 Two things follow:
 
-- **Naming is the test — and the bar is a specific, honest name, not just any
-  name.** Almost any block can be given *some* label; that's not the test.
-  If the only name you can find is generic (`handleStuff`, `MiscWrapper.vue`)
-  **or** merely plausible-sounding without actually describing one clear
-  responsibility, the split is along the wrong seam — find the boundary that
-  earns a real name, or leave it inline until one emerges.
+- **Naming is the test.** The name has to be specific and honest: if the best
+  you can find is `handleStuff` or `MiscWrapper.vue`, or the accurate name needs
+  an "and" in it, the seam is wrong. Find the boundary that earns a real name,
+  or leave it inline until one emerges.
 - **Extraction is its own commit** when you're separating duplication or
   responsibilities that predate your change. A unit that exists only because of
   the feature you're building belongs in the feature commit.

From b93c820d37769729fafd0c5906226af4c16f114d Mon Sep 17 00:00:00 2001
From: James Manuel <moodyjmz@users.noreply.github.com>
Date: Fri, 24 Jul 2026 03:36:18 +0200
Subject: [PATCH 04/14] docs: correct CI-failure claims and close checklist
 gaps
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The stale-base warning claimed DCO failures that base staleness cannot
cause, and implied "Check build changes" fails only on stale bases when
it fails on any uncompiled src change by design — replace it with the
actual mechanism (CI builds the merge ref, so a moved main makes
compiled assets drift again). State the conventional-commit headline
format CI enforces on every commit, restore the reviewability rationale
for atomic commits, rename the commit section to a single concern, note
/compile requires a maintainer, and add the composer gates (lint,
cs:check, psalm, openapi) that the JS-only pre-PR checklist omitted.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: James Manuel <moodyjmz@users.noreply.github.com>
---
 AGENTS.md | 38 +++++++++++++++++++++++++++++---------
 1 file changed, 29 insertions(+), 9 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 74e855c..83d1197 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -8,14 +8,19 @@ For AI coding agents. Human contributors: see `README.md`.
 git fetch origin && git checkout -b <branch> origin/main
 ```
 
-A stale base fails CI's `npm-build` "Check build changes" job or DCO, and a
-refactor may have moved the code you're about to edit. You'll re-check `main`
-before opening the PR too — see below.
+CI builds your branch merged with current `main`, so a stale base can fail the
+`npm-build` "Check build changes" job even after a recompile, and a refactor
+may have moved the code you're about to edit. You'll re-check `main` before
+opening the PR too — see below.
 
-## One concern per commit, signed off
+## Commit discipline
 
-`git commit -s` — CI enforces DCO. A functional change, a cleanup, and a docs
-update are three commits.
+One concern per commit: a functional change, a cleanup, and a docs update are
+three commits. A reviewer can verify a single-concern diff; a mixed one can
+only be trusted.
+
+CI checks every commit: conventional-format headline (`fix:`, `feat:`,
+`docs:`, ...) and DCO sign-off — `git commit -s`.
 
 Confident AI output still needs splitting: a flawless-looking helper and a real
 bug can come from the same commit.
@@ -30,9 +35,9 @@ git restore --staged js css
 ```
 
 `js/` and `css/` are build output; the `nextcloud-command` bot compiles and
-commits them to your branch after someone comments `/compile` on the PR — say in
-the description that it's still needed. `.githooks/pre-commit` is a backstop,
-not a plan.
+commits them to your branch after a maintainer comments `/compile` on the PR —
+say in the description that it's still needed. `.githooks/pre-commit` is a
+backstop, not a plan.
 
 ## Reuse before you write
 
@@ -75,8 +80,23 @@ Two things follow:
 
 ```bash
 git fetch origin && git log --oneline HEAD..origin/main   # rebase if non-empty
+```
+
+If the change touches `src/` (JS/Vue/CSS):
+
+```bash
 npm run lint
 npm run stylelint
 npm run test:unit
 npm run build   # then unstage js/ css/
 ```
+
+If the change touches PHP:
+
+```bash
+composer lint
+composer cs:check
+composer psalm
+composer openapi   # if controllers or routes changed
+                   # commit openapi*.json — unlike js/css, this one is tracked
+```

From 25fe5d7e16d76b8e0558ac7cc68efe1eb6b0feb0 Mon Sep 17 00:00:00 2001
From: James Manuel <moodyjmz@users.noreply.github.com>
Date: Fri, 24 Jul 2026 04:00:45 +0200
Subject: [PATCH 05/14] docs: treat auth checks and psalm findings as immovable

The app's roadmap is token-authenticated document serving, where a
widened TTL or a casually added #[NoCSRFRequired] is an authentication
change, not a fix. Require reviewable justification for loosening any
check, ban secrets and file paths from logs, and close the baseline
escape hatch for psalm findings.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: James Manuel <moodyjmz@users.noreply.github.com>
---
 AGENTS.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 83d1197..e9b5f6e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -76,6 +76,18 @@ Two things follow:
   responsibilities that predate your change. A unit that exists only because of
   the feature you're building belongs in the feature commit.
 
+## Never loosen a security check
+
+Auth here is deliberate: `#[NoAdminRequired]` and `#[NoCSRFRequired]` on a
+controller method are security decisions, not boilerplate — adding one to fix
+a 403 needs a reason a reviewer can check. The same goes for widening a token
+TTL, scope, or validation to make a test or client pass: that is the
+authentication being loosened.
+
+No tokens, secrets, or user file paths in logs or error messages. Render
+user-controlled strings as text, never markup. Psalm findings get fixed, not
+baselined.
+
 ## Before opening a PR
 
 ```bash

From 1f187d19cb6236ba4e5f87ca83aacca25b0528ff Mon Sep 17 00:00:00 2001
From: James Manuel <moodyjmz@users.noreply.github.com>
Date: Fri, 24 Jul 2026 04:01:03 +0200
Subject: [PATCH 06/14] docs: make accessibility a release gate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Enterprise deployments audit accessibility, so regressions block
releases rather than queueing as polish. State the floor: accessible
names on interactive elements, no colour-only state, keyboard
reachability with visible focus — and note that @nextcloud/vue
components ship these semantics already, reinforcing reuse. The
current eslint config carries no accessibility rules, so the section
says plainly that the check is manual rather than pointing at a gate
that does not exist.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: James Manuel <moodyjmz@users.noreply.github.com>
---
 AGENTS.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index e9b5f6e..20c508e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -88,6 +88,18 @@ No tokens, secrets, or user file paths in logs or error messages. Render
 user-controlled strings as text, never markup. Psalm findings get fixed, not
 baselined.
 
+## Accessibility is a gate, not polish
+
+Enterprise deployments audit it; regressions block releases.
+
+`@nextcloud/vue` components ship accessible semantics — one more reason
+hand-rolled markup loses. On top of that: every interactive element gets an
+accessible name (icon-only buttons need `aria-label`), state is never colour
+alone, and anything clickable is keyboard-reachable with visible focus.
+
+Nothing enforces this yet — `npm run lint` carries no accessibility rules —
+so check the list above by hand before the PR.
+
 ## Before opening a PR
 
 ```bash

From 6e1f06ef1f1b9dfa85ff2d00a72a9949fb35990d Mon Sep 17 00:00:00 2001
From: James Manuel <moodyjmz@users.noreply.github.com>
Date: Fri, 24 Jul 2026 04:01:22 +0200
Subject: [PATCH 07/14] docs: bound resource use by default

Anything that grows with a user's file count gets capped or paginated,
component-registered listeners and timers are released in onUnmounted
(TemplateSection.vue is the in-repo shape), file contents stream rather
than load whole since office documents have no upper size, and new
dependencies justify their bundle cost.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: James Manuel <moodyjmz@users.noreply.github.com>
---
 AGENTS.md | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 20c508e..4ac520d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -100,6 +100,17 @@ alone, and anything clickable is keyboard-reachable with visible focus.
 Nothing enforces this yet — `npm run lint` carries no accessibility rules —
 so check the list above by hand before the PR.
 
+## Bound work and memory
+
+- No unbounded reads: cap or paginate anything that grows with a user's file
+  count, in queries and in rendered rows.
+- Release what you register: listeners, timers, and observers added in a
+  component are removed in `onUnmounted` — see `TemplateSection.vue`.
+- Stream file contents; never read a whole document into memory — office
+  files have no upper size.
+- A new dependency pays its way in bundle size: check what an import drags in
+  before adding it.
+
 ## Before opening a PR
 
 ```bash

From 16f8f1b962b6ec3ba0e30c40f3e54927231a6a7d Mon Sep 17 00:00:00 2001
From: James Manuel <moodyjmz@users.noreply.github.com>
Date: Fri, 24 Jul 2026 04:01:40 +0200
Subject: [PATCH 08/14] docs: require spec siblings for extracted units
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The repo pairs every unit in src/utils/ and src/components/ with a
.spec.ts sibling, but the guidance only asked for testable structure,
not tests. State the requirement as a completion criterion under
commit discipline — inside the separation-of-concerns section it
would read as a tax on the extraction that section argues for.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: James Manuel <moodyjmz@users.noreply.github.com>
---
 AGENTS.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 4ac520d..26361d6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -22,6 +22,9 @@ only be trusted.
 CI checks every commit: conventional-format headline (`fix:`, `feat:`,
 `docs:`, ...) and DCO sign-off — `git commit -s`.
 
+A new unit lands with its `.spec.ts` sibling in the same commit —
+`src/utils/` and `src/components/` pair each unit with one; follow that.
+
 Confident AI output still needs splitting: a flawless-looking helper and a real
 bug can come from the same commit.
 

From 1782d3adfd069ab0cea1fa9096204d68f0d98063 Mon Sep 17 00:00:00 2001
From: James Manuel <moodyjmz@users.noreply.github.com>
Date: Fri, 24 Jul 2026 04:04:08 +0200
Subject: [PATCH 09/14] docs: route contestable calls to the human
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A rule an agent can satisfy by articulating a plausible reason is a
rule an agent will self-certify past — the security-attribute and
bundle-cost judgements are exactly where that happens, not just the
extraction seams. Name those triggers and generalize to any call a
reviewer could reasonably contest. Unattended, the fallback is the
narrower, easier-to-reverse option rather than "leave it", which an
agent would treat as inapplicable when the contested change blocks
the feature; the PR-description flag applies either way, since an
agent cannot reliably tell whether it is unattended.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: James Manuel <moodyjmz@users.noreply.github.com>
---
 AGENTS.md | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 26361d6..c18a53b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -114,6 +114,16 @@ so check the list above by hand before the PR.
 - A new dependency pays its way in bundle size: check what an import drags in
   before adding it.
 
+## When the call is contestable, ask
+
+Two defensible seams from the naming test, a cleanup that would grow the PR,
+a security attribute you can justify but a reviewer might not accept, a
+dependency whose bundle cost is arguable — anywhere a reviewer could
+reasonably want the other option, put the choice to the human driving the
+session before committing to it; unattended, take the narrower option — the
+one that's easier to reverse in review. Either way, flag the call in the PR
+description.
+
 ## Before opening a PR
 
 ```bash

From a5971323fc00f9d9df353618bfdf3ad3ce34cf8f Mon Sep 17 00:00:00 2001
From: James Manuel <moodyjmz@users.noreply.github.com>
Date: Mon, 10 Aug 2026 09:58:28 +0200
Subject: [PATCH 10/14] docs: require updating existing specs on signature
 changes

The spec-sibling rule above only covers new units. It doesn't say
anything about changing what an existing tested function returns or
accepts, which is a different failure mode: the specs already exist,
they just go stale silently until someone runs test:unit. That gap is
what let #100 change getAllOfficeFiles's return shape while leaving
two existing spec files asserting the old one.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Signed-off-by: James Manuel <moodyjmz@users.noreply.github.com>
---
 AGENTS.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index c18a53b..ebe16d6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -25,6 +25,12 @@ CI checks every commit: conventional-format headline (`fix:`, `feat:`,
 A new unit lands with its `.spec.ts` sibling in the same commit —
 `src/utils/` and `src/components/` pair each unit with one; follow that.
 
+Changing what an existing function returns or accepts isn't done until every
+`.spec.ts` that mocks or asserts on it reflects the new shape — `grep` the
+function name across `src/**/*.spec.ts` before considering the commit
+finished. `npm run test:unit` (see the checklist below) will catch the ones
+you miss, but only if you run it before opening the PR, not after.
+
 Confident AI output still needs splitting: a flawless-looking helper and a real
 bug can come from the same commit.
 

From 58f11e5d004dcd59dba15551c83803a7dda62131 Mon Sep 17 00:00:00 2001
From: James Manuel <moodyjmz@users.noreply.github.com>
Date: Mon, 10 Aug 2026 09:59:18 +0200
Subject: [PATCH 11/14] docs: forbid weakening tests to force a pass
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Neither of the two testing rules just added stops the failure mode
where a red test gets skipped, deleted, or de-fanged (a dulled matcher,
a dropped case) instead of the underlying code getting fixed — the PR
still goes green, the bug just loses its test coverage along the way.
State it as its own rule so a genuine behavior-change update to an
expectation isn't confused with silencing one.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Signed-off-by: James Manuel <moodyjmz@users.noreply.github.com>
---
 AGENTS.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index ebe16d6..7cd3250 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -31,6 +31,14 @@ function name across `src/**/*.spec.ts` before considering the commit
 finished. `npm run test:unit` (see the checklist below) will catch the ones
 you miss, but only if you run it before opening the PR, not after.
 
+A red test means the code is wrong or the behavior it pins changed on
+purpose — never fix it by loosening what it checks. Skipping (`.skip`,
+`.todo`), deleting a case, or dulling a matcher (`toEqual` → `toBeTruthy`,
+dropping an assertion) to turn a failure green makes the test stop proving
+anything; it's the bug staying in, with the evidence removed. If behavior
+did change on purpose, update the expectation and say in the commit why the
+new value is correct — not just that it now matches what the code outputs.
+
 Confident AI output still needs splitting: a flawless-looking helper and a real
 bug can come from the same commit.
 

From 03b0fb722286db617c0271b3c64523970d4ba69c Mon Sep 17 00:00:00 2001
From: James Manuel <moodyjmz@users.noreply.github.com>
Date: Mon, 10 Aug 2026 10:10:30 +0200
Subject: [PATCH 12/14] docs: add composer test:unit to the PR checklist

The JS checklist runs test:unit; the PHP one didn't, despite
composer.json defining the same script. A branch about tightening
test discipline shouldn't skip reminding PHP changes to run their
own tests before opening a PR.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Signed-off-by: James Manuel <moodyjmz@users.noreply.github.com>
---
 AGENTS.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/AGENTS.md b/AGENTS.md
index 7cd3250..843c465 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -159,6 +159,7 @@ If the change touches PHP:
 composer lint
 composer cs:check
 composer psalm
+composer test:unit
 composer openapi   # if controllers or routes changed
                    # commit openapi*.json — unlike js/css, this one is tracked
 ```

From 1f09ef73efbfe93dd7ba59ac06ef639e3023ebf0 Mon Sep 17 00:00:00 2001
From: James Manuel <moodyjmz@users.noreply.github.com>
Date: Mon, 10 Aug 2026 10:10:41 +0200
Subject: [PATCH 13/14] docs: require a regression test for behavioral bug
 fixes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The two existing testing rules cover a new unit and a changed
signature, but not the most common shape a bug fix takes: same
signature, corrected behavior. That gap is exactly what PR #85's own
regression test closed (newest-first cap) and what the DAV
orderby/limit fix in #100 needed independent of its return-shape
change — the doc's rules shouldn't cover the shapes that made this
branch's own examples but miss the shape most bug fixes actually are.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Signed-off-by: James Manuel <moodyjmz@users.noreply.github.com>
---
 AGENTS.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 843c465..6bb730c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -31,6 +31,12 @@ function name across `src/**/*.spec.ts` before considering the commit
 finished. `npm run test:unit` (see the checklist below) will catch the ones
 you miss, but only if you run it before opening the PR, not after.
 
+Fixing a bug in existing logic — same signature, different behavior — still
+needs a regression test pinning the corrected behavior, in the same commit
+as the fix. Without one, nothing stops the bug from coming back next time
+this code is touched, and the fix reads as untested even in a file that
+already has specs.
+
 A red test means the code is wrong or the behavior it pins changed on
 purpose — never fix it by loosening what it checks. Skipping (`.skip`,
 `.todo`), deleting a case, or dulling a matcher (`toEqual` → `toBeTruthy`,

From d95e23105a93978a7032727106a5c2ba875ae704 Mon Sep 17 00:00:00 2001
From: James Manuel <moodyjmz@users.noreply.github.com>
Date: Mon, 10 Aug 2026 10:10:56 +0200
Subject: [PATCH 14/14] docs: allow fixing a genuinely wrong test, with
 justification
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The red-test rule only recognized two causes: the code is wrong, or
behavior changed on purpose. That left no legitimate path for a test
that was simply wrong to begin with (asserting on a mock, flaky),
which would either force fixing code that isn't broken or invite a
dishonest "behavior changed" justification to stay compliant. Add the
third case, gated the same way as the others — justify it in the
commit — and route it through the existing contestable-call rule
rather than leaving it as a unilateral judgment call.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Signed-off-by: James Manuel <moodyjmz@users.noreply.github.com>
---
 AGENTS.md | 19 ++++++++++++-------
 1 file changed, 12 insertions(+), 7 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 6bb730c..86a3145 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -37,13 +37,18 @@ as the fix. Without one, nothing stops the bug from coming back next time
 this code is touched, and the fix reads as untested even in a file that
 already has specs.
 
-A red test means the code is wrong or the behavior it pins changed on
-purpose — never fix it by loosening what it checks. Skipping (`.skip`,
-`.todo`), deleting a case, or dulling a matcher (`toEqual` → `toBeTruthy`,
-dropping an assertion) to turn a failure green makes the test stop proving
-anything; it's the bug staying in, with the evidence removed. If behavior
-did change on purpose, update the expectation and say in the commit why the
-new value is correct — not just that it now matches what the code outputs.
+A red test means one of three things: the code is wrong, the behavior it
+pins changed on purpose, or the test itself is wrong — asserting on a mock
+instead of real behavior, or flaky. Only the last two justify touching the
+test, and both require the commit message to say which it is and why, not
+just that the failure went away. Deciding a test is wrong is itself a
+contestable call (see below) — if you're not certain, ask rather than
+deleting the evidence.
+
+Skipping (`.skip`, `.todo`), deleting a case, or dulling a matcher
+(`toEqual` → `toBeTruthy`, dropping an assertion) to turn a failure green
+without that justification makes the test stop proving anything; it's the
+bug staying in, with the evidence removed.
 
 Confident AI output still needs splitting: a flawless-looking helper and a real
 bug can come from the same commit.