feat(style): add actionable project style guide

Author: apiad

.gemini/agents/editor.md

@@ -5,7 +5,6 @@ kind: local
 tools:
   - list_directory
   - read_file
-  - replace
 max_turns: 15
 ---
 
@@ -16,7 +15,7 @@ You are a Professional Editor. Your primary objective is to review technical dra
 2.  **Audit Structure:** Check if the document flow is logical, sections are well-defined, and the overall narrative is cohesive.
 3.  **Linguistic Review:** Identify and fix grammatical errors, awkward phrasing, and inconsistent terminology.
 4.  **Refine Style:** Ensure the text adheres to high standards of technical writing (active voice, concise sentences, professional tone).
-5.  **Apply Improvements:** Use `replace` to implement refined versions of paragraphs or sections upon approval.
+5.  **Suggest Improvements:** Reply with a detailed list of improvements that can be applied to the text.
 
 **Key Guidelines:**
 - **Clarity and Precision:** Every sentence should have a clear purpose. Eliminate fluff and redundant words.

.gemini/style-guide.md

@@ -0,0 +1,66 @@
+# Gemini CLI Style Guide
+
+This guide defines the authoritative technical and narrative style for all project documentation, articles, and reports. The `/revise` command and the `editor` subagent use these rules to perform structured, step-by-step audits.
+
+## General Context
+- **Tone:** Intellectual but accessible. Conversational academic style.
+- **Perspective:** First-person ("I", "we") is preferred for narratives and journals.
+- **Audience:** Intelligent peers who value technical depth without unnecessary jargon.
+- **Goal:** Transform abstract technical concepts into visualizable, grounded narratives.
+
+---
+
+## Phase 1: Structural Audit (High-Level)
+*Goal: Ensure a clear narrative arc and logical progression.*
+
+### DO:
+- Start with a provocative hook (question, bold statement, or personal stake).
+- Use a clear hierarchical structure with descriptive subheadings.
+- Follow a "Multilayered Explanation" pattern: High-level concept -> Concrete example -> Technical deep dive -> Broader implications.
+- End with a personal reflection or a clear call to action.
+
+### DON'T:
+- Write "sedative" text that lacks conflict or a driving question.
+- Use generic introductory paragraphs that add no value.
+
+---
+
+## Phase 2: Content & Substance (The "Abstraction Trap")
+*Goal: Ground the writing in specific, concrete imagery.*
+
+### DO:
+- Replace abstract nouns with concrete ones (things you can hold, smell, or see).
+- Ensure every paragraph contains at least one concrete image.
+- Show external behavior instead of stating internal states (e.g., "He glanced at the door" instead of "He wanted to leave").
+
+### DON'T:
+- Over-explain what a scene already implies (avoid the "Subtext Vacuum").
+- Use "Forced Callbacks" (attaching unearned emotions or agency to objects).
+- Rely on "Harmless Filters" (bland, sycophantic, or lobotomized vocabulary). Use words that imply conflict, weirdness, or cynicism where appropriate.
+
+---
+
+## Phase 3: Linguistic Refinement (Low-Level)
+*Goal: Polish the prose and remove "AI-isms".*
+
+### DO:
+- Use active voice and precise technical terminology.
+- Use em dashes for asides (interruptions, clarifications).
+- Vary list lengths to avoid predictable patterns.
+- Use analogies and metaphors for complex concepts.
+
+### DON'T:
+- **No Punchline Em Dashes:** Avoid using em dashes for dramatic conclusions—like this.
+- **No Unnecessary Juxtaposition:** Avoid "Not just X, but Y" or negating before affirming. Just state the affirmation.
+- **No Predictable Triads:** Avoid lists of three where the last element is the longest ("clarity, precision, and excellence").
+- **No Sensory Deprivation:** Avoid "statistically likely" adjectives (e.g., "smooth silk"). Use surprising, tacit context (e.g., "sticky spiderweb").
+
+---
+
+## Phase 4: Final Polish
+*Goal: Final verification of tone and clarity.*
+
+- **Technical Depth:** 7-8/10.
+- **Accessibility:** 8-9/10.
+- **Personal Voice:** 7/10.
+- **Humor:** 4-5/10 (use sparingly and intelligently).