feat: add shared workflow and skill references in .agents and update GEMINI.md for clarity on workspace structure

README.md

@@ -6,6 +6,8 @@ This repository is not the product codebase. It is an operational context layer
 
 The reusable logic lives in `core/`. The clean project second brain lives in `project-knowledge/`. Agent operating memory lives in `agent-memory/`. Fidelity-specific setup lives in the active profile under `profiles/fidelity/`.
 
+Shared cross-platform workflow/rule content lives in `.agents/`. OpenCode reads that content through `.opencode/` compatibility paths, and Gemini-compatible entry context starts at `GEMINI.md`.
+
 ---
 
 ## Purpose
@@ -70,6 +72,23 @@ Agent operating memory.
 - `workflows/` -> AI-to-AI prompting and workspace behavior model
 - `maps/` -> agent-side navigation maps
 
+### /.agents
+
+Shared cross-platform workflow and rule source.
+
+- `workflows/` -> reusable workflow definitions used by OpenCode-compatible commands and Antigravity-compatible workflow views
+- `rules/` -> reusable skill/rule content
+- `skills/` -> skill-path compatibility layer pointing at `rules/`
+
+### /.opencode
+
+OpenCode runtime surface.
+
+- `commands/` -> OpenCode slash commands, currently linked to `.agents/workflows/`
+- `skills/` -> OpenCode skills, currently linked to shared `.agents/` content
+- `agents/` -> OpenCode agent definitions
+- `plugins/` -> OpenCode-specific plugins
+
 ### /core
 
 Project-independent workspace logic.
@@ -230,6 +249,13 @@ Project commands live under `.opencode/commands/` and are intended to:
 
 This keeps AI output tied to the latest workspace state instead of relying on chat memory alone.
 
+Cross-platform note:
+
+- `.agents/` is the shared source of truth for reusable workflows/rules
+- `.opencode/` is the OpenCode execution layer
+- `.agent/` may exist as a naming alias for tools that look for singular agent directories
+- `GEMINI.md` is the Gemini CLI entrypoint for shared workspace context
+
 ---
 
 ## Generic Commands