agora-server: Instructions file for Gemini CLI

This file provides a summary of my core understanding of the Agora project, which I use as my primary context for our sessions.

For a detailed plan of future work, see [[ROADMAP.md]]. For a log of completed work, see [[DONE.md]]. For essays and poems on the project's philosophy, see [[PHILOSOPHY.md]].

---

Memories & Mandates

• Feature Flag Protocol: Always enable new feature flags in LocalDevelopmentConfig first. Never enable in AlphaConfig or ProductionConfig without explicit user instruction and prior local verification.
• Git Operations: The user prefers to handle commits themselves, or explicitly approve them. Always git status and git diff before asking. NEVER use git add . or git add -A under any circumstances, as other agents might be operating concurrently. Always explicitly list the exact files to add: git add <file1> <file2>.
• Development: Run npm run build after TypeScript changes. Do not use ./run-dev.sh; the user manages the server.
• Tone: Be direct and technical. Use metaphors sparingly (e.g., for "Federation").

---

Understanding the Agora (as of 2025-09-21)

This is a summary of my understanding of the project's philosophy and technical principles based on our collaboration.

The Agora of Flancia's Intents (The "Why")

The project's goal is to create a Free Knowledge Commons with a focus on:

• Connecting Digital Gardens: Weaving together individual, user-owned collections of notes into a larger whole.
• Collaborative Problem-Solving: Building a space where knowledge is not just stored but actively used and composed into tools.
• Low Barrier to Contribution: Prioritizing simple, durable formats (like plain text files) to make it easy for anyone to participate.
• Playful Experimentation: Fostering a delightful and evolving user experience.

The Agora Protocol (The "How")

The protocol is a set of architectural patterns that enable the Agora's vision:

• Decentralization: The filesystem is the ultimate source of truth. The server is a lens, not a silo.
• Nodes are Concepts, Subnodes are Utterances: A key distinction where abstract topics ([[Calculus]]) are composed of concrete contributions (@user/calculus-notes.md).
• Composition over Centralization: Nodes are built by pulling and combining content from other, more specialized nodes (e.g., [[170]] pulling from [[calc/170]]).
• Everything Has a Place (No 404s): Every possible query resolves to a node, turning dead ends into invitations to contribute.