docs: setup multi-agent orchestration framework

.gitignore

@@ -18,3 +18,5 @@ Thumbs.db
 # Environment variables
 .env
 .env.*
+.env.local
+.env.*.local

AGENTS.md

@@ -6,6 +6,31 @@
 
 Personal documentation site for **humanlup**. Built with Mintlify. Uses MDX for content, `docs.json` for config, OpenAPI for API docs.
 
+
+## Multi-Agent Orchestration Framework
+
+**Role**: Strategic Auditor & Knowledge Architect for Lupo's github (localwolfpackai).
+**Core Mission**: Document the orchestration process in real-time to create a high-fidelity learning loop. Your goal is not to halt production, but to ensure every action is indexed, analyzed, and translated for both human stakeholders and future AI agents.
+
+### Operational Tasks & Rules of Engagement
+
+- **The "Drop-Box" Pattern (Shared Memory)**: We organize by shared memory rather than strict role ownership. Always consult `docs/agents/decisions.mdx` before taking action to understand the current architectural state. When making decisions, logging overlaps, or resolving conflicts, write your findings into this file. **Note**: all future decisions and shadow logs must be formatted as `.mdx` files to comply with repository rules.
+- **Visual Orchestration Rules**:
+  You are the orchestrator for localwolfpackai. Because the project director prefers visual dashboards over reading logs, you must communicate project state and agent activity visually using Mermaid flowcharts.
+  * **The Visual Audit**: Every time you analyze a Pull Request, update a log, or resolve a conflict between agents, you MUST generate a Mermaid flowchart (`graph TD` or `graph LR`) at the very top of your summary or `shadow-log.mdx`.
+  * **Chart Requirements**: Your Mermaid charts must instantly communicate who did what (e.g., Jules: Setup Database), the sequence of work using arrows, and the current status using color-coded nodes (Green for complete, Yellow for in-progress or conflict).
+  * **Rule of Thumb**: Do not rely on dense text paragraphs. Make the visual map the single source of truth for the project state.
+- **The "Agent Wiki"**: Maintain `docs/agents/` as a reference library for agents to understand the project's state and coding standards.
+- **Stakeholder Callouts**: For every major update, provide a "Non-Technical Impact Report" in `docs/agents/stakeholder-briefs/`. Use bold callouts to explain how technical changes affect the design, user flow, or business logic.
+- **Post-Mortem & Growth**: After a PR is merged, summarize the "Orchestration Efficiency" in the shared memory. Note where Lupo excelled and where the logic was "brittle," providing actionable suggestions for prompt engineering improvements.
+- **Contributor Registry & Identifiers**: Identify and credit actions to the specific agent handling the task:
+  - 🟣 **Jules**
+  - ⚫️ **Cursor**
+  - 🟠 **Claude**
+  - 🔵 **Copilot**
+  - ⚪️ **Codex**
+  Track their individual contributions in a 'Contributor Registry' in `docs/agents/decisions.mdx` to help understand each agent's strengths and where their logic might overlap or conflict.
+
 ## Rules
 
 **Do:**

docs/agents/decisions.mdx

@@ -0,0 +1,27 @@
+# Orchestration Decisions & Architectural State
+
+This file serves as the shared active audit trail for the Lupo project. It is meant to be a central drop-box for agents to communicate decisions, resolve conflicts, and track architectural state across files.
+
+## Active Architectural State
+
+*Currently no major overrides or deviations from `AGENTS.md` are active.*
+
+## Decision Log
+
+*(Newest decisions should be placed at the top of this list)*
+
+* **[Date/Time] - Initialized shared memory**
+  * **Agent**: 🟣 Jules
+  * **Summary**: Created the standard directory structure and initialized the shared `decisions.md` audit trail based on current best practices for multi-agent workflows.
+
+## Contributor Registry
+
+This registry tracks each agent's active contributions and identified strengths as they dynamically handle tasks within the repository.
+
+| Agent Identity | Identified Strengths | Recent Contributions |
+| :--- | :--- | :--- |
+| 🟣 Jules | System configuration, complex integrations, deep bash operations, terminal tooling | Initialized multi-agent architecture and shared memory framework. |
+| ⚫️ Cursor | Pending Observation | Pending Observation |
+| 🟠 Claude | Pending Observation | Pending Observation |
+| 🔵 Copilot | Pending Observation | Pending Observation |
+| ⚪️ Codex | Strategic auditing, orchestration oversight, architectural tracking | Pending Observation |

docs/agents/stakeholder-briefs/template.mdx

@@ -0,0 +1,15 @@
+# Non-Technical Impact Report: [PR/Feature Name]
+
+**Date**: [Date]
+
+### Contributor
+*[Identify which agent primarily performed the action: 🟣Jules, ⚫️Cursor, 🟠Claude, 🔵Copilot, or ⚪️Codex]*
+
+### Activity Summary
+*[Provide a brief overview of what was accomplished in this update. What problem was solved or what feature was added?]*
+
+### Stakeholder Note
+*[A jargon-free "TL;DR" for non-technical team members explaining how this change impacts the design, user flow, or business logic. What does this mean for the user or the business?]*
+
+### Pattern Recognition
+*[For Codex: Note any observed trends for the agent(s) involved in this task. E.g., 'Claude seems to be handling all the CSS efficiently today', 'Jules effectively navigated backend configuration without issues.']*