Rules: Consolidate JS/Go code comment guidance into shared file

Move the duplicated doc-comment guidance out of go-code-style.md and
frontend-rules.md into .claude/rules/code-comments.md so both languages
share one source. Mirror the same block in AGENTS.md for Codex, which
does not load .claude/rules/. Raise the follow-up line cap from 1-2 to
up to 3 to match what compact comments actually need in practice.

.claude/CLAUDE.md

@@ -140,7 +140,8 @@ Before promoting a claim from `CLAUDE.md`, `AGENTS.md`, a memory entry, or anoth
 
 Topic-specific conventions live under `.claude/rules/` and are loaded alongside this file:
 
-- `go-code-style.md`, `go-testing.md` — Go style, doc comments, package boundaries, test patterns, fixtures.
+- `code-comments.md` — shared JS/Go doc comment rules (length cap, what to omit); referenced by both style files.
+- `go-code-style.md`, `go-testing.md` — Go style, package boundaries, test patterns, fixtures.
 - `frontend-rules.md` — JS/Vue code style, formatting, dependencies, tests, Playwright, translations.
 - `commit-and-docs-style.md` — commit-message format, GitHub issue templates, spec heading style.
 - `safety-and-security.md` — Git/data safety, destructive commands, file I/O and archive-extraction policies, HTTP download helpers.

.claude/rules/code-comments.md

@@ -0,0 +1,11 @@
+## JS/Go Code Comment Rules
+
+Doc comments for packages and exported identifiers must be complete sentences that begin with the name of the thing being described and end with a period.
+
+A doc comment is **required** for every function (including unexported helpers), as well as for every non-trivial Vue `methods:` / `computed:` / watcher:
+- Keep comments **compact** and default to one line for WHAT in the format `// Name does X.`. Skip trivial getters (`isOpen: () => this.open`).
+- Add up to three follow-up lines (`// …`) only when the WHY is non-obvious: a hidden invariant, a workaround that would otherwise be undone by a future cleanup, a contract a reader can't infer from the code.
+- For short examples in comments, indent code instead of using backticks.
+- If readers can derive the WHY from the function body or a nearby line, leave it out. Multi-paragraph comments belong in specifications, package README files, or issue descriptions — never in the source itself.
+
+> **Don't include in code comments:** Issue / PR numbers, "previously…" history, alternatives considered, what the function used to do, references to old commits, names of subsequent reviewers, or any narrative that names the change rather than the steady-state behavior. That context belongs in commit messages, specs, or handover notes.

.claude/rules/frontend-rules.md

@@ -1,13 +1,10 @@
 ## Frontend Code Style & Test Coverage
 
-- **Doc comments are required, but compact.** Every new JS function and every non-trivial Vue `methods:` / `computed:` / watcher entry needs a doc comment — but the default is ONE `// Name does X.` line (see `src/options/themes.js`, `src/common/util.js`). Skip trivial getters (`isOpen: () => this.open`).
-- **Length cap.** One line for WHAT. Add 1–2 short lines (`// …`) only when the WHY is non-obvious: a hidden invariant, a workaround that would otherwise be undone by a future cleanup, a contract a reader can't infer from the code. If the next reader can derive it from the function body or a nearby line, leave it out. Multi-paragraph comments belong in specs or PR descriptions, never in source.
-- **Don't include in code comments:** issue / PR numbers, "previously…" history, alternatives considered, what the function used to do, references to old commits, names of subsequent reviewers, or any narrative that names the change rather than the steady-state behavior. Those belong in commit messages, specs, or handover notes.
-- Vue Single-File Components: one-line doc comment above the default export and a one-liner above each non-trivial method, computed property, or watcher. Same length cap as above.
-- Test new JS functions (including helpers) and new Vue components whenever practical; update existing tests when behavior changes. When a unit test is impractical (DOM-heavy flows, third-party widget integration), the doc comment is still mandatory — it's the minimum bar.
-- **JavaScript only — do not introduce TypeScript.** The frontend is a pure JS + Vue SFC codebase: no `.ts` files, no `tsconfig.json`, no `<script lang="ts">` blocks. JSDoc type annotations in comments are fine; full TS migrations are out of scope.
-- Use the Options API in Vue components (consistent with the rest of the codebase); do not introduce Composition API or `<script setup>`.
-- **State management:** shared state lives in reactive singleton modules under `src/common/` and `src/app/` (e.g., `app/session.js`, `common/config.js`, `common/clipboard.js`, `common/log.js`) that export a `reactive()` / `ref()` object directly; components access them via `import` or via the globally-installed `$config` / `$session` plugins. Do not introduce Vuex, Pinia, or new ad-hoc stores — extend an existing singleton or add a new one alongside its peers in `common/` or `app/`.
+- **Comments:** Follow the code comment rules in `code-comments.md`.
+- **Tests:** Test new JS functions (including helpers) and new Vue components whenever practical; update existing tests when behavior changes. When a unit test is impractical (DOM-heavy flows, third-party widget integration), the doc comment is still mandatory — it's the minimum bar.
+- **State:** Shared state lives in reactive singleton modules under `src/common/` and `src/app/` (e.g., `app/session.js`, `common/config.js`, `common/clipboard.js`, `common/log.js`) that export a `reactive()` / `ref()` object directly; components access them via `import` or via the globally-installed `$config` / `$session` plugins. Do not introduce Vuex, Pinia, or new ad-hoc stores — extend an existing singleton or add a new one alongside its peers in `common/` or `app/`.
+- **Vue/Vuetify:** Use the Options API in Vue components (consistent with the rest of the codebase); do not introduce Composition API or `<script setup>`.
+- **TypeScript:** Do not introduce TypeScript. The frontend is a pure JS + Vue SFC codebase: no `.ts` files, no `tsconfig.json`, no `<script lang="ts">` blocks. JSDoc type annotations in comments are fine; full TS migrations are out of scope.
 
 ## Frontend Formatting
 

.claude/rules/go-code-style.md

@@ -1,12 +1,9 @@
 ## Go Code Style
 
-- Run `make lint-go` (golangci-lint) after Go changes; prefer `golangci-lint run ./internal/<pkg>/...` for focused edits.
-- Doc comments for packages and exported identifiers must be complete sentences that begin with the name of the thing being described and end with a period.
-- Every new function (including unexported helpers) needs a doc comment — but keep it compact. Default to ONE line: `// Name does X.` Add a short follow-up line only when the WHY is non-obvious (hidden invariant, subtle workaround, contract a reader can't infer from the body). If the next reader can derive it from the code, leave it out.
-- **Don't include in code comments:** issue / PR numbers, "previously…" history, alternatives considered, what the function used to do, references to old commits, names of subsequent reviewers, or any narrative that names the change rather than the steady-state behavior. That context belongs in commit messages, specs, or handover notes.
-- For short examples inside comments, indent code rather than using backticks; godoc treats indented blocks as preformatted.
-- Every Go package must contain a `<package>.go` file in its root (e.g. `internal/auth/jwt/jwt.go`) with the standard license header and a short package description comment.
-- Go is formatted by `gofmt` with tabs. Do not hand-format indentation. After edits run `make fmt-go` (gofmt + goimports).
+- **Comments:** Follow the code comment rules in `code-comments.md`.
+- **Packages:** Every Go package must contain a `<package>.go` file in its root (e.g. `internal/auth/jwt/jwt.go`) with the standard license header and a short package description comment.
+- **Format:** Go is formatted by `gofmt` with tabs. Do not hand-format indentation. After edits run `make fmt-go` (gofmt + goimports).
+- **Linting:** Run `make lint-go` (`golangci-lint`) after Go changes; prefer `golangci-lint run ./internal/<pkg>/...` for focused edits.
 
 ## Package Boundaries
 

AGENTS.md

@@ -90,27 +90,32 @@ Title Case rules (Chicago-style, with code- and path-aware normalization):
 - Frontend: Vue 3 plus Vuetify 3 under `frontend/`.
 - Local dev and CI use Docker Compose; Traefik provides local TLS via `*.localssl.dev`.
 - Code in `pkg/*` must not import from `internal/*`. If you need config, entity, or DB access, add code under `internal/`.
-- Shared Go filesystem rules:
+- Shared Go rules:
+  - After Go edits, run `make fmt-go` and keep `gofmt` tab indentation.
+  - Every added/modified Go function, including unexported helpers, must have focused test coverage in the corresponding `*_test.go` files; update existing tests or add new ones as needed.
+  - Every Go package must contain a root `<package>.go` file with the standard license header and a short package description comment.
   - Use `pkg/fs` permission constants: `fs.ModeDir`, `fs.ModeFile`, `fs.ModeConfigFile`, `fs.ModeSecretFile`, and `fs.ModeBackupFile`.
   - When importing the stdlib `io/fs`, alias it to avoid collisions, for example `iofs "io/fs"` or `gofs "io/fs"`.
   - Do not pass stdlib `io/fs` mode flags where permission bits are expected.
   - Prefer `filepath.Join` for filesystem paths and `path.Join` only for URL paths.
   - Normalize slash-based logical paths stored in DB, config, or API payloads with `clean.SlashPath(...)`.
-- Shared Go style rules:
-  - After Go edits, run `make fmt-go` and keep `gofmt` tab indentation.
-  - Doc comments for packages and exported identifiers must be complete sentences that begin with the described name and end with a period.
-  - Every new function (including unexported helpers) needs a doc comment — but keep it compact: default to ONE `// Name does X.` line. Add 1–2 short follow-up lines only when the WHY is non-obvious (hidden invariant, subtle workaround, contract a reader can't infer from the body).
-  - Every new Go function, including unexported helpers, must have focused test coverage in the corresponding `*_test.go` files; update existing tests or add new ones as needed.
-  - For short examples in comments, indent code instead of using backticks.
-  - Every Go package must contain a root `<package>.go` file with the standard license header and a short package description comment.
-- Shared JS/Vue style rules:
-  - Every new JS function and every non-trivial Vue `methods:` / `computed:` / watcher entry needs a doc comment. Same compact default as Go: ONE `// Name does X.` line; 1–2 short follow-up lines only for non-obvious WHY. Trivial getters (e.g. `isOpen: () => this.open`) can skip the comment.
-- Shared JS/Vue testing rules:
-  - New JavaScript functions, including helpers, should be tested whenever practical; update existing tests or add new ones as needed.
-  - New Vue components should have component-test coverage, and existing component tests should be updated as needed when behavior changes.
-- Do not include in any code comment (Go or JS): issue / PR numbers, "previously…" history, alternatives considered, what the function used to do, references to old commits or reviewers, or any narrative that names the change instead of the steady-state behavior. That context belongs in the commit message, the spec, or a handover note — never in source.
+- Shared JS/Vue rules:
+  - Added/modified JavaScript functions, including helpers, should be tested whenever practical; update existing tests or add new ones as needed.
+  - Added/modified Vue components should have component-test coverage, and existing component tests should be updated as needed when behavior changes.
 - When adding a metadata source such as `SrcOllama` or `SrcOpenAI`, update both `internal/entity/src.go` and `frontend/src/common/util.js` so backend and UI stay aligned.
 
+### JS/Go Code Comments
+
+Doc comments for packages and exported identifiers must be complete sentences that begin with the name of the thing being described and end with a period.
+
+A doc comment is **required** for every function (including unexported helpers), as well as for every non-trivial Vue `methods:` / `computed:` / watcher:
+- Keep comments **compact** and default to one line for WHAT in the format `// Name does X.`. Skip trivial getters (`isOpen: () => this.open`).
+- Add up to three follow-up lines (`// …`) only when the WHY is non-obvious: a hidden invariant, a workaround that would otherwise be undone by a future cleanup, a contract a reader can't infer from the code.
+- For short examples in comments, indent code instead of using backticks.
+- If readers can derive the WHY from the function body or a nearby line, leave it out. Multi-paragraph comments belong in specifications, package README files, or issue descriptions — never in the source itself.
+
+> **Don't include in code comments:** Issue / PR numbers, "previously…" history, alternatives considered, what the function used to do, references to old commits, names of subsequent reviewers, or any narrative that names the change rather than the steady-state behavior. That context belongs in commit messages, specs, or handover notes.
+
 ## Agent Runtime
 
 - Detect container mode by checking for `/.dockerenv`.