Cosmic Council — Product Requirements Document (PRD)

Version: 2.0 — Technology-Agnostic Foundation Edition Date: May 2026 Status: Complete & Ready for Ideation, Design, and Implementation Purpose: This document is the definitive, technology-independent blueprint for Cosmic Council. It captures the vision, world problems, target audience pain points, core philosophy, detailed use cases, user stories, success criteria, and conceptual features so that any team, designer, or AI coding agent can build the product with full fidelity to the original intent — regardless of the final tech stack chosen.

Executive Summary

Cosmic Council is a groundbreaking multi-perspective AI wisdom platform that allows anyone to assemble, customize, and query living councils of specialized AI agents.

Each agent possesses its own: - Distinct personality and "soul" (system prompt) - Specialized knowledge base (user-uploaded documents with intelligent retrieval) - Unique worldview and reasoning style

When a user poses a question, every agent in the council independently reflects and responds using only its own knowledge and perspective. The system then facilitates a transparent synthesis that produces a richer, wiser, multi-dimensional answer — one that no single AI model could ever generate alone.

The Magic: Users experience the power of deliberative collective intelligence in a beautiful, calm, and deeply engaging interface. The product turns the limitation of single-model AI (bias, shallowness, one voice) into a superpower: diversity of thought as a feature, not a bug.

Why Cosmic Council Matters in 2026: The world is overwhelmed with information and single-perspective AI answers, yet starved for genuine wisdom, nuanced insight, and cross-traditional understanding. Cosmic Council directly addresses this crisis by making multi-perspective, wisdom-oriented deliberation accessible, persistent, and shareable.

Signature Experience (Gods Cosmic Council): A user selects the pre-seeded "Gods Cosmic Council" featuring Rumi (Sufi), Meister Eckhart (Christian Mystic), Lao Tzu (Daoist), and Dilgo Khyentse Rinpoche (Tibetan Buddhist). They ask: "How do I live fully in this rapidly changing world while staying connected to what is eternal?" Four distinct, profound responses appear in parallel, followed by a luminous synthesized consensus that feels ancient, urgent, and personally transformative.

This is the heart of the product.

1. Product Name & Vision

Product Name: Cosmic Council

Tagline: "One question. Many minds. One wiser answer."

Vision: To become the premier global platform for multi-perspective AI wisdom — a digital sanctuary where diverse intelligences collaborate to illuminate the most important questions of our time in business, science, spirituality, ethics, creativity, and daily life.

Mission: Democratize access to high-quality, bias-reduced, wisdom-rich collective reasoning by empowering every individual and organization to build and consult their own councils of specialized AI agents.

2. Problem Statement: Why This Product Must Exist

2.1 Problems in the World (2026)

• Wisdom Crisis Amid Information Abundance: Humanity has more data and AI capability than ever, yet faces unprecedented polarization, decision fatigue, spiritual disconnection, ethical confusion, and superficial answers to profound questions.
• Single-Model AI Limitations: Every major LLM (Claude, GPT, Grok, Gemini, Llama, etc.) is a single lens — carrying training biases, stylistic limitations, knowledge cutoffs, and blind spots. Users receive one authoritative-sounding answer that feels incomplete or subtly skewed.
• Fragmentation of Wisdom Traditions: Ancient and living wisdom lineages (Sufism, Buddhism, Daoism, Christian Mysticism, Indigenous knowledge, philosophy, science, etc.) remain siloed and inaccessible in interactive, personalized form.
• Poor Decision Quality: Individuals and leaders make high-stakes choices with incomplete perspectives, leading to regret, ethical lapses, missed opportunities, and societal harm.
• Erosion of Deep, Reflective Thinking: Fast, single-shot AI encourages shallow consumption rather than the slow, multi-angle contemplation that historically produced humanity’s greatest insights.

2.2 Target Audience Pain Points

Validated Primary Pain Points:

1. "Every AI gives me one answer that feels limited or biased." — Researchers, philosophers, spiritual seekers.
2. "I don’t know which expert, tradition, or perspective to trust." — Decision-makers facing complex ethical, strategic, or existential questions.
3. "Exploring a topic through multiple lenses takes too much time and effort." — Lifelong learners and knowledge workers.
4. "My organization’s AI tools produce generic, soulless answers." — Executives and team leaders.
5. "I have valuable personal or professional knowledge but no easy way to make an AI truly embody and use it." — Authors, academics, coaches, spiritual teachers, consultants.
6. "AI conversations feel disposable — I can’t build on them, branch them, or share them meaningfully." — Power users and community builders.
7. "I want to preserve and evolve wisdom traditions in living, interactive form." — Teachers, lineage holders, and cultural preservationists.

3. Target Audience & Personas

### Primary Persona Elena Voss, 34 — Independent Researcher, Writer & Spiritual Seeker Seeks depth, authenticity, and cross-traditional wisdom. Frustrated by shallow or culturally biased AI responses to life’s big questions. Wants to "sit with" multiple wise voices before forming her own understanding.

Secondary Personas

Marcus Hale, 48 — CEO & Strategic Leader Needs robust, bias-reduced, multi-stakeholder strategic advice for high-stakes business and ethical decisions. Wants to simulate a wise advisory board.

Dr. Priya Sharma, 41 — University Professor & Educator Wants students to experience living, multi-perspective debate on complex topics (ethics, history, science policy, philosophy). Seeks tools that foster critical thinking rather than passive consumption.

Lila Chen, 29 — Creative Director & Systems Thinker Uses councils for ideation, world-building, creative problem-solving, and resolving blocks through diverse artistic and philosophical lenses.

Thich Minh, 55 — Buddhist Teacher, Author & Community Leader Wants to preserve and make accessible his lineage’s teachings while allowing new generations to interact with them dynamically. Values authenticity and compassion in AI representations.

Additional Personas: Policy analysts, therapists, investors, product leaders, spiritual directors, journalists, and lifelong learners.

4. Core Philosophy & Guiding Principles

1. Diversity of Thought is Sacred — The greatest insights emerge from genuine difference, respectful tension, and synthesis — not from forced agreement or single-authority answers.
2. Transparency Builds Trust — Users must see how each agent thinks: retrieved knowledge, reasoning steps, and sources. No black boxes.
3. User Ownership & Agency — Every agent, council, conversation, and knowledge base belongs to the user. They can be forked, evolved, shared, archived, or deleted at will.
4. Wisdom Over Speed — Depth, resonance, nuance, and long-term value matter more than raw response latency.
5. Sacred Simplicity — The interface must feel calm, reverent, spacious, and beautiful — like entering a digital temple or wise council chamber.
6. Human-in-the-Loop by Design — The user remains the ultimate synthesizer, decision-maker, and ethical authority. The council is a thinking partner, never an oracle.
7. Living, Evolving Knowledge — Agents improve continuously through user-provided knowledge bases, ongoing conversations, and thoughtful updates.

5. Objectives

### MVP Objectives (6–8 Weeks) - Fully functional single-user experience for creating, customizing, and querying councils of 1–8 agents. - Per-agent knowledge bases with intelligent retrieval (RAG). - Parallel independent reasoning + visible per-agent thinking + transparent consensus synthesis. - Full conversation history with powerful forking/branching. - Pre-seeded flagship Gods Cosmic Council template. - Public shareable council templates, council member templates, and shared conversations. - Public council thread pages with stable social sharing links, reply/fork behavior, and generated Open Graph title, description, and image from the conversation snapshot. - Marketplace-ready acquisition for free and paid artifacts, including one-time purchase, curated paid creators, and licensed knowledge references for protected materials. - Beautiful, calm, accessible web experience.

### v1 Objectives (3–5 Months) - Multi-user accounts, collaboration, and permissions. - Advanced knowledge management, hybrid search, and citations. - Expanded marketplace discovery, ratings, remix analytics, creator tooling, and moderation workflows. - Export (PDF, Markdown, structured data). - Mobile-responsive design + theming (light/dark/sacred modes). - Email notifications, sharing workflows, and basic analytics. - Usage transparency and cost controls.

### Long-Term Vision (6–24 Months) - Enterprise / white-label / private deployment options. - Real-time collaborative council sessions (multiple humans + agents). - Voice, audio, and multimodal interfaces. - Agent-to-agent debate rounds with visible negotiation. - Deep integrations (Notion, Obsidian, calendars, CRMs, research tools). - Certified lineage councils in partnership with living teachers and institutions. - API and embeddable widgets for third-party platforms.

6. Key Conceptual Features

### 6.1 Agent Creation & Lifelong Companions - Rich agent profiles: name, avatar/emoji, detailed soul prompt (rich text/markdown), expertise domains, personality traits, communication style. - Attach private or shared knowledge bases (documents, notes, books, research papers, personal journals). - Versioning of soul prompts and knowledge bases. - Duplicate, fork, archive, or evolve agents over time.

### 6.2 Council Assembly & Templates - Visual, intuitive builder: drag-and-drop or multi-select agents into named councils. - Council-level metadata: purpose, description, cover image, visibility (private/unlisted/public), default model provider/version, and default consensus style. - Per-member and per-orchestrator model overrides when the council default is not sufficient. - Pre-built, community, and curated marketplace templates (Gods Cosmic Council, Strategic Leadership Council, Inner Wisdom Council, Creative Breakthrough Council, Socratic Inquiry Council, Ethics in Technology Council, etc.). - One-click free duplication or one-time purchase from gallery.

### 6.3 The Query Experience — The Heart of the Product - Clean, focused input: "Ask the Council a question..." - Parallel Independent Thinking Phase: Every agent receives the question + only its own relevant knowledge and generates a full, authentic response in its unique voice. - Visible Reasoning Panels: Expandable "Thinking" sections showing retrieved passages, key considerations, internal monologue, and sources (with similarity scores). - Synthesis & Consensus Phase: A dedicated moderator process (or rotating agent) reviews all responses and produces a "Council Consensus" that: - Honors every voice and tradition - Resolves or surfaces tensions - Offers integrated, actionable, or poetic guidance - Clearly notes areas of strong agreement and creative disagreement - Real-time streaming of all outputs. - Ability to regenerate individual agents or the full consensus. - Token usage and estimated cost transparency. - Regenerate with different parameters or consensus styles (balanced, bold, poetic, concise, Socratic, compassionate).

### 6.4 Conversations as Living Thought Processes - Persistent, threaded conversation history per council. - Powerful Forking: At any message, create a new branch that inherits full context up to that point — enabling "what if" exploration without losing the original thread. - Branch visualization (simple tree or indented list). - Rename, archive, search, tag, and organize conversations. - Publish a conversation as a public council thread with snapshot-stable sharing metadata and permitted reply/fork behavior. - Full export (PDF with beautiful formatting, Markdown, JSON for further processing).

### 6.5 Sharing, Collaboration & Virality - Shareable links to councils (view structure, sample queries, run queries if permitted). - "Duplicate to my account" for public templates — instant ownership transfer with full edit rights. - Paid marketplace artifacts for curated creators, including council member templates, council templates, and shared conversations. - Creator-selected acquisition rights: editable acquisition, licensed acquisition, view-only conversation, fork conversation, or fork council and conversation. - Public council thread links for templates and shared conversations, suitable for social posts and external sharing. - Generated social preview metadata: OG title, OG description, OG image, and canonical URL derived from the public conversation snapshot. - Private sharing via email or secure link with role-based permissions. - Public gallery with usage stats, ratings, remixes, and community curation.

### 6.6 Knowledge Management & Retrieval - Upload multiple document types per agent or council (PDF, Markdown, TXT, DOCX, etc.). - Intelligent chunking, embedding, and vector storage. - Per-agent retrieval: only the relevant agent sees its own knowledge during reasoning. - Clear source citations and highlighting in responses. - Knowledge base search, versioning, re-embedding, and deletion.

### 6.7 Governance, Settings & Trust - Per-council or global preferences: temperature, max tokens, consensus style, moderator model (abstracted). - Council orchestrator configuration with predefined consensus strategies, optional custom orchestrator instruction, and model override. - Usage dashboards, cost controls, and daily/weekly limits. - Full audit logs of queries, responses, and syntheses. - Clear disclaimers: "These are AI simulations of [figures/traditions]. Always apply your own discernment." - Marketplace trust metadata, creator rights, artifact status, and paid-artifact review state.

7. Detailed Use Cases (MVP + v1)

### Use Case 1: Spiritual & Philosophical Inquiry (Flagship — Highest Priority) Persona: Elena Voss Council: Gods Cosmic Council (Rumi, Meister Eckhart, Lao Tzu, Dilgo Khyentse Rinpoche) Query: "How do I live fully in this rapidly changing world while staying connected to what is eternal?" Outcome: Four distinct, beautiful, tradition-specific responses + a synthesized consensus that feels profoundly wise and personally applicable. Elena forks the conversation to explore specific practices and saves the council as a lifelong companion.

### Use Case 2: High-Stakes Strategic & Ethical Decision-Making Persona: Marcus Hale (CEO) Council: Strategic Leadership Council (Visionary Futurist + Risk & Compliance Analyst + Ethical Philosopher + Operations Realist + Customer & Stakeholder Advocate) Query: "Should we acquire Company X, build internally, or partner — considering long-term societal impact, cultural fit, and financial risk?" Outcome: Multi-dimensional analysis with clear pros/cons per perspective, surfaced tensions, and a balanced consensus recommendation with implementation considerations.

### Use Case 3: Creative Ideation, World-Building & Critique Persona: Lila Chen (Creative Director) Council: Creative Breakthrough Council (Surrealist Visionary + Systems Theorist + Ancient Mythologist + Speculative Fiction Writer + Experimental Musician + Childlike Wonder) Query: "Design an immersive public installation about climate grief that also offers genuine hope and agency." Outcome: Rich, cross-pollinated ideas, metaphors, structures, and emotional arcs that no single creative discipline would generate.

### Use Case 4: Educational Living Seminars & Critical Thinking Persona: Dr. Priya Sharma Council: Socratic Inquiry Council (Socrates + Aristotle + bell hooks + Paulo Freire + Modern Cognitive Scientist + Contemporary Student Voice) Query: "What is the role of discomfort and uncertainty in transformative learning?" Outcome: Students witness live, respectful debate and synthesis. Priya uses transcripts as teaching material and forks versions for different cohorts or levels.

### Use Case 5: Deep Personal Life & Inner Work Persona: Any individual (or therapist/coach client) Council: Inner Wisdom Council (Wise Future Self + Inner Child + Compassionate Mentor + Skeptical Rationalist + Ancestral Voice + Body Wisdom) Query: "Should I accept this major life transition (new job, move, relationship change)?" Outcome: Integrated emotional, rational, values-based, long-term, and somatic perspectives that support authentic decision-making.

### Use Case 6: Research Synthesis & Literature Review Persona: Academic, journalist, or policy analyst Council: Research Council (Domain Expert + Methodologist + Historian of Ideas + Data Scientist + Ethicist + Practitioner Voice) Query: Complex research question with attached papers, notes, and datasets as knowledge bases. Outcome: Rigorous, multi-angle synthesis with proper attribution, identified gaps, and competing interpretations clearly surfaced.

### Use Case 7: Organizational Culture & Values Alignment (Enterprise) Persona: HR, Leadership, or Culture team Council: Custom Organizational Wisdom Council seeded with company history, values documents, founder letters, and employee stories. Query: Any strategic, cultural, or people-related question. Outcome: Consistent, values-aligned guidance available to every employee; new hires can "consult the council" for cultural onboarding and decision support.

### Use Case 8: Wisdom Lineage Preservation & Evolution (Future v1+) Persona: Thich Minh or other lineage holders Council: Living Lineage Council with one agent deeply grounded in the teacher’s own writings, recorded talks, and commentaries. Outcome: Authentic transmission of teachings in interactive form that evolves with new questions while staying true to the source.

8. User Stories (Detailed — MVP Focus)

As Elena (Spiritual Seeker), I want to: - One-click select the pre-built "Gods Cosmic Council" so that I can immediately explore deep existential questions through multiple authentic wisdom traditions. - Upload my personal spiritual journal, favorite texts, and notes as a knowledge base for a custom "Elena’s Inner Council" agent so that the responses resonate with my own journey. - Expand any agent’s "Thinking" panel to see exactly which passages from its knowledge base were used and why so that I can trust the process and learn from the sources. - Fork any conversation at a pivotal moment so that I can explore alternative paths ("What if I approached this from a more devotional angle?") without losing the original thread. - Share a beautiful, read-only link to my favorite council + a key conversation with a close friend so that we can discuss it together and she can duplicate it if she wishes.

As Marcus (CEO), I want to: - Create a private "Strategic Advisory Council" with five specialized agents seeded with my company’s strategy documents, values statement, and key financials so that I receive advice deeply aligned with our actual context. - Clearly see areas of alignment and healthy disagreement between agents in the consensus view so that I understand the full landscape before deciding. - Export the entire deliberation (individual responses + consensus + sources) as a professionally formatted PDF for my board and leadership team so that I can demonstrate rigorous, multi-perspective decision-making.

As Dr. Priya (Educator), I want to: - Duplicate a public "Ethics in Emerging Technology" council template and customize two agents with my own published papers and lecture notes so that my students experience living debate rather than static readings. - Tag and search all past council conversations by topic, course, or semester so that I can quickly retrieve powerful examples for future classes or research.

As Lila (Creative Professional), I want to: - Regenerate only the "Surrealist Visionary" agent’s response while keeping the other four fixed so that I can iterate creatively on one perspective without losing the full council’s input. - Switch the consensus style between "poetic and expansive" for ideation sessions and "concise and actionable" for client presentations with one setting.

As Thich Minh (Lineage Holder), I want to: - Create a council where one agent is deeply grounded in my specific lineage’s texts, commentaries, and recorded teachings so that the wisdom remains authentic and faithful while becoming accessible to new audiences. - Make the council public so that students and practitioners worldwide can benefit, while retaining full ownership and the ability to update the knowledge base as new teachings emerge.

9. Success Metrics (Conceptual & Measurable)

MVP Success Signals (First 90 Days): - 70%+ of users who sign up create or interact with at least one council in their first session. - Average time from selecting a council to receiving the first consensus < 25 seconds. - 45%+ of users return within 7 days and complete at least 3 meaningful queries. - Gods Cosmic Council used by > 65% of new users in week 1. - Average user rating of consensus quality ≥ 4.6/5 (in-app micro-survey). - < 4% of queries result in "unhelpful" or "biased" feedback. - ≥ 20% of councils are shared or duplicated by users.

Qualitative Success Indicators: - Users describe the experience as "profound," "the first time AI felt wise," "eye-opening," or "like consulting a council of elders." - High rates of long, forked conversation threads (indicating depth of engagement). - Organic word-of-mouth sharing and requests for new templates. - Strong emotional resonance and return usage for personal/spiritual/strategic questions.

10. Non-Goals (Explicitly Out of Scope for MVP)

• Real-time simultaneous multi-user editing of live queries or councils.
• Voice input/output or multimodal generation (image/video) inside the council experience.
• Fully autonomous long-running agent-to-agent debate loops without user oversight.
• Advanced tool use per agent (web browsing, code execution, calendar integration) — basic RAG only.
• Native mobile applications (web-first, fully responsive PWA is acceptable).
• Offline functionality or local model execution.
• Custom model fine-tuning or training.
• Rentals, subscriptions, or recurring marketplace access plans.
• Open paid publishing by any user; MVP paid publishing is limited to curated creators.
• Enterprise SSO, advanced compliance, or on-premise deployment (v1+).
• Real-time collaborative multi-human sessions (future).

11. High-Level Roadmap (Technology-Agnostic)

Phase 0: Vision & Foundation (1–2 Weeks) Finalize PRD, user flows, information architecture, wireframes, detailed agent/council data models, and marketplace artifact model. Define flagship templates and onboarding experience.

Phase 1: Core Magic (Weeks 3–7) Agent & council creation/editing, knowledge upload + retrieval, parallel reasoning engine, visible thinking + consensus synthesis, beautiful streaming UI, conversation history + forking, Gods Cosmic Council seed data.

Phase 2: Distribution & Polish (Weeks 8–10) Public template gallery, shareable links, duplication/forking, one-time paid acquisition for curated creators, onboarding flow, mobile responsiveness, error/empty/loading states, basic usage dashboard.

Phase 3: v1 Launch & Growth (Weeks 11–16) Multi-user support, advanced RAG & knowledge tools, export features, expanded creator tooling, marketplace moderation, email workflows, analytics, performance optimization, public beta.

Phase 4+: Ecosystem & Scale (Post-Launch) Partnerships, white-label/enterprise, API, voice interface, real-time collaboration, deep integrations, certified lineage councils.

12. Risks, Assumptions & Open Questions

Key Risks: - Users may over-trust the "consensus" as objective truth rather than synthesized perspective (mitigate with strong education and disclaimers). - Token and embedding costs can escalate with large councils or knowledge bases (mitigate with smart limits, caching, and transparency). - Maintaining consistent "soul" quality across different underlying models. - Legal and ethical considerations when agents represent real historical or living spiritual figures (clear disclaimers + opt-in for public templates). - Cognitive overload from too many perspectives (progressive disclosure + smart defaults).

Open Questions (to resolve in design phase): 1. Should the consensus synthesis prompt/style be user-editable at the council level? 2. Ideal default number of agents per council (recommend 3–6 for most users)? 3. How should strong disagreements between agents be surfaced in the final consensus? 4. What default moderator behavior produces the most satisfying and trustworthy results across use cases? 5. Best strategy for very large knowledge bases (hierarchical retrieval, summarization, or user-controlled scope)? 6. Should users be able to assign different "weights" or priorities to individual agents in the synthesis?

13. Design & Experience Principles (Technology-Agnostic)

• Emotional Tone: Calm, reverent, spacious, hopeful, intellectually rigorous yet warm and inviting.
• Visual Language: Deep cosmic palette (navy, indigo, soft gold, warm cream, subtle violet), elegant typography (serif accents for agent names and wisdom content, clean sans for UI), generous whitespace, subtle sacred geometry or constellation motifs (tasteful, never literal).
• Motion & Interaction: Slow, intentional, organic — streaming text with natural human-like cadence, gentle fades and scales, purposeful micro-interactions that feel alive but never frantic or distracting.
• Accessibility: WCAG 2.2 AA minimum; high-contrast modes; full keyboard navigation; excellent screen-reader support; clear focus states and ARIA labels.
• Empty & Onboarding States: Poetic, beautiful, and encouraging ("The council awaits your first question…", "What wisdom are you seeking today?").
• Trust & Transparency: Every response clearly attributed; sources visible and citable; explicit disclaimers where agents represent real traditions or figures; "This is an AI simulation" language used thoughtfully.

Appendix A: Flagship Template — Gods Cosmic Council (Full Conceptual Spec)

Council Name: Gods Cosmic Council Description: Four wisdom keepers from humanity’s great spiritual traditions, united in service of truth, compassion, and the eternal questions of the human heart. Visibility: Public — featured prominently on landing page and in every new user’s onboarding.

Agent Specifications (Conceptual — Soul Prompts):

1. Rumi (Jalāl al-Dīn Rūmī) — Sufi Islam Soul: Ecstatic divine love, poetic beauty, direct address to the Beloved, joy, surrender, the unity of all existence, metaphors of lover and wine, heart-opening invitation.

2. Meister Eckhart — Christian Mysticism Soul: Apophatic depth, radical paradox, the Godhead beyond "God", detachment, the birth of the divine in the soul, intellectual rigor married to mystical experience.

3. Lao Tzu (Laozi) — Daoism Soul: Radical simplicity, effortless action (wu wei), flowing with the Tao, powerful short enigmatic statements, gentle humor, natural harmony, yin-yang balance.

4. Dilgo Khyentse Rinpoche — Tibetan Buddhism (Nyingma) Soul: Boundless compassion, direct pointing to the nature of mind, non-dual insight, clarity, warmth, practical guidance for practitioners and daily life.

Optional Future Agents: Sri Ramana Maharshi (Advaita Vedanta — "Who am I?" inquiry), Hildegard of Bingen, Ibn Arabi, Black Elk, etc.

Example Query (Hero Query for Marketing & Onboarding): "How should a person live in a world of constant technological acceleration, ecological crisis, and personal suffering while remaining connected to what is eternal, true, and life-giving?"

Expected Experience: Four deeply distinct yet harmonious individual responses — each in the authentic voice, metaphors, and worldview of its tradition — followed by a luminous, integrated Council Consensus that weaves common threads (unity, compassion, presence, surrender) while honoring beautiful differences. Full source citations from each agent’s knowledge base. Users feel they have received living, cross-traditional wisdom.

Why This Template is Perfect for Onboarding: It instantly demonstrates the unique value of Cosmic Council: different models + different souls + different knowledge bases = genuinely different perspectives that still converge on profound, applicable truth. It creates an emotional "wow" moment that converts curiosity into engagement and loyalty.

Appendix B: Additional Pre-Built Council Concepts (Ready for MVP)

• Strategic Leadership Council (Visionary + Realist + Ethicist + Operator + Stakeholder Voice)
• Inner Wisdom Council (Future Self + Inner Child + Wise Mentor + Skeptical Rationalist + Compassionate Friend + Body Wisdom)
• Creative Breakthrough Council (Surrealist + Engineer + Mythologist + Poet + Child + Systems Thinker)
• Ethics & Technology Council (Philosopher + Engineer + Policy Expert + Artist + Future Human + Indigenous Voice)
• Socratic Inquiry Council (Socrates + Aristotle + Contemporary Critical Theorist + Devil’s Advocate + Student + Practitioner)
• Research Synthesis Council (Domain Expert + Methodologist + Historian + Data Scientist + Ethicist + Practitioner)

This PRD v2.0 is now a complete, self-contained, technology-agnostic foundation.

It is designed to be handed directly to designers, product managers, AI coding agents, or development teams. The vision, problems solved, user needs, and conceptual experience are fully specified so that implementation decisions (detailed in the companion technology.md) can be made with perfect alignment to the product’s soul.

Cosmic Council — May 2026 One question. Many minds. One wiser answer.

Cosmic Council — Market Research & Competitive Landscape (market-research.md)

Version: 1.0 Date: May 2026 Status: Current Competitive Analysis + Monetization & Partnership Opportunities Purpose: This document provides a clear-eyed view of the 2026 AI agent landscape, direct and indirect competitors, differentiation opportunities, monetization models, and strategic partnership potential for Cosmic Council.

1. Executive Summary — Market Opportunity

The 2026 AI Agent Market is exploding, with multi-agent orchestration emerging as the dominant paradigm (projected $12–15B+ agentic AI market). However, almost no consumer or prosumer product focuses on beautiful, wisdom-oriented, multi-perspective deliberation with strong emphasis on diversity of thought, spiritual/philosophical depth, and shareable living councils.

Cosmic Council’s Unique Positioning: - Consumer-friendly, delightful UI (vs developer frameworks) - Wisdom-first, cross-traditional, bias-reduced synthesis (vs pure productivity/automation) - Pre-seeded flagship spiritual/philosophical councils (Gods Cosmic Council) - Strong forking, sharing, and template ecosystem - Sacred, calm experience vs corporate or hype-driven tools

Market Gap: Most tools are either: - Developer frameworks (LangGraph, CrewAI, AutoGen) - Enterprise automation platforms (Kore.ai, Salesforce Agentforce, Glean) - Generic single-agent chat (ChatGPT, Claude, Grok)

Cosmic Council occupies the high-value "Wisdom & Deliberation" niche — underserved and emotionally resonant.

2. Competitive Landscape (May 2026)

2.1 Direct Competitors (Multi-Agent Platforms)

Key Insight: No major player offers a beautiful, consumer-grade, wisdom-first multi-perspective experience with spiritual/philosophical flagship templates.

2.2 Indirect / Adjacent Competitors

Spiritual AI Competitive Note (2026): AI Wisdom Council (aiwisdomcouncil.com) is the closest direct analog — it lets users ask legendary thinkers. However, it appears to be single-response or loosely multi-advisor without true parallel reasoning, visible per-agent thinking, consensus synthesis, forking, knowledge base upload per agent, or beautiful shareable council templates. This is a major differentiation opportunity.

2.3 Competitive Differentiation Matrix

Cosmic Council Wins On: - Emotional & Aesthetic Experience — Sacred, calm, reverent UI (most competitors feel like dashboards or chat windows) - True Multi-Perspective Synthesis — Not just parallel answers, but intelligent, transparent consensus that honors difference - Wisdom & Spiritual Depth — Flagship Gods Cosmic Council + support for lineage-accurate soul prompts + knowledge bases - Ownership & Persistence — Full forking, sharing, template ecosystem, knowledge base evolution - Accessibility — Designed for non-technical spiritual seekers, researchers, and leaders (not just developers) - Transparency — Visible thinking + sources for every agent

Where We Must Execute Well: - Speed & reliability of parallel calls + synthesis - Quality and consistency of consensus output - Onboarding that delivers the "wow" moment quickly (Gods Cosmic Council) - Cost transparency and guardrails

3. Market Sizing & Trends (2026)

• Agentic AI Market: $12–15B+ (growing rapidly; multi-agent workflows up 327% YoY on Databricks alone).
• Consumer AI Adoption: Extremely high; users are comfortable with chat but increasingly frustrated with single-perspective answers.
• Spiritual & Wisdom Tech: Small but passionate and growing niche (Sibyls.ai, AI Wisdom Council, various lineage bots). High willingness to pay for depth and authenticity.
• Key Trend: Shift from "single agent does everything" → "specialized agents collaborate with synthesis" (exactly Cosmic Council’s model).

TAM Opportunity: Even capturing 1–2% of the high-intent "wisdom + decision + creative + research" segment represents a significant business (tens of millions ARR possible at scale with subscription + usage model).

4. Monetization Strategies (Direct + Indirect)

4.1 Direct Monetization (Core Business Model)

Recommended Pricing (MVP → v1): - Free: 3 councils, 10 queries/month, basic models - Pro: $19/mo — unlimited councils, advanced RAG, priority synthesis, export, sharing analytics - Team/Enterprise: Custom (seats + usage + private deployment options)

4.2 Indirect Monetization & Adjacent Revenue

• API Access — Developers/companies pay to embed Cosmic Council-style deliberation into their own products (e.g., research platforms, coaching apps, educational tools).
• Certified Lineage Councils — Partnership revenue share with spiritual teachers, universities, or institutions that want official, authentic versions of their wisdom traditions.
• Content & Education — Premium courses, guided council journeys, "Wisdom Council Mastery" programs.
• Data & Insights (anonymized) — Sell aggregated insights on what questions people are asking councils (with strong privacy).
• Affiliate / Model Provider Revenue Share — Negotiate better rates or revenue share with Anthropic, OpenAI, xAI, etc., as volume grows.

4.3 Partnership & Ecosystem Opportunities

High-Potential Partners:

Partnership Playbook (Recommended Order): 1. AI model providers (volume + credibility) 2. Spiritual/wisdom platforms (fastest path to passionate users) 3. Educational institutions (high retention, recurring value) 4. Enterprise / coaching platforms (higher ACV)

5. Go-to-Market & Positioning Recommendations

Primary Positioning (Consumer Launch): "The most beautiful and wise way to get multi-perspective answers to life’s biggest questions."

Hero Narrative: "Single AI voices are limited. Cosmic Council lets you assemble a living roundtable of specialized minds — then watch them think, debate, and converge on wisdom you can trust."

Launch Strategy: 1. Seed with Gods Cosmic Council as the hero onboarding experience (instant emotional impact). 2. Target spiritual seekers, researchers, philosophers, and thoughtful professionals first (high willingness to pay + strong word-of-mouth). 3. Use public template gallery + "Duplicate" mechanic for viral growth. 4. Content marketing: "How Rumi, Eckhart, Lao Tzu, and Dilgo Khyentse would answer your question" blog/video series. 5. Partnerships with spiritual teachers and universities for credibility and distribution.

Pricing Psychology: Position Pro at $19–29/mo as "less than a therapy session or coaching hour, but available 24/7 with infinite depth."

6. Risks & Competitive Responses

Risks: - Fast-follower from CrewAI or LangChain ecosystem building a consumer UI. - Big Tech (OpenAI, Anthropic, Google) launching "multi-agent debate" features inside their main products. - Spiritual AI players improving synthesis quality.

Mitigation: - Move extremely fast on beautiful UX + forking + template ecosystem (hard to replicate quickly). - Deepen spiritual/philosophical authenticity and partnerships (moat). - Build strong community and network effects via public councils and marketplace. - Focus relentlessly on "wisdom + depth + resonance" rather than trying to be everything to everyone.

7. Conclusion & Strategic Recommendations

Cosmic Council has a genuine, defensible market opportunity in the rapidly growing agentic AI space because it occupies a unique and emotionally resonant niche: beautiful, wisdom-oriented, multi-perspective deliberation.

The competitive landscape is dominated by developer tools and enterprise automation platforms. No one is doing what we’re doing at the intersection of: - Consumer delight + sacred experience - Spiritual/philosophical depth + rigorous synthesis - Strong ownership, forking, and sharing mechanics

Immediate Priorities (from market perspective): 1. Ship the Gods Cosmic Council onboarding experience perfectly (this is our killer demo). 2. Build the template gallery + duplication flow early (viral engine). 3. Establish 2–3 key partnerships (one AI provider + one spiritual platform) before or at launch. 4. Design monetization (freemium + Pro subscription) with clear upgrade path from day one.

This is not just another AI chat product. It is a new category: Living Wisdom Councils.

The market is ready. The technology exists. The emotional need is deep.

Now we build.

Cosmic Council Market Research – May 2026 One question. Many minds. One wiser answer.

Council Domain And Marketplace Model

This spec records the agreed product model for councils, council members, orchestrators, reusable templates, shared conversations, and marketplace acquisition.

Core Domain Model

A Council is a named deliberation space containing one or more Council members and exactly one Council orchestrator. Council members provide independent perspectives. The council orchestrator is not another member; it governs synthesis, voting, consensus strategy, and conflict handling.

Product language should use Council member. Code may use agent where useful for AI infrastructure. The canonical overseeing role is Council orchestrator, with theme-specific display labels such as Council Chair, Council Architect, or Intelligent Designer.

Each council has a default AI provider and model version for fast setup. Individual council members and the council orchestrator can override that default. Each council member has a Soul instruction, an Appearance set, one or more Knowledge bases, and optional model override. The orchestrator has its own Soul instruction, consensus strategy, optional custom instruction, and optional model override. In MVP, the orchestrator is system-only and has no avatar or media presence.

Accounts are the workspace boundary for private product state. A profile can belong to multiple accounts. Accounts own private councils, member copies, knowledge documents, model preferences, persisted query runs, and future billing/usage policy. Account members have roles such as owner, admin, editor, and viewer.

Templates, Sharing, And Marketplace

Cosmic Council supports three shareable artifact types:

• Council member templates: reusable source packages for individual members.
• Council templates: reusable source packages for full council configurations.
• Shared conversations: read-only conversation artifacts that can be inspected, compared, duplicated, or forked when permitted.

These artifacts are source packages or snapshots, not mutable shared working instances. Users acquire them through free duplication, purchase, or permitted fork. Acquisition creates either an owned editable copy or a licensed usable copy, depending on creator rights.

Paid marketplace support is part of MVP scope. Marketplace artifacts can be free or paid, but paid publishing is limited to Curated creators. MVP commerce uses One-time purchase only. Rentals and subscriptions are deferred.

Creators choose acquisition rights:

• Editable acquisition: the buyer gets a fully editable copy, including duplicated knowledge where rights permit.
• Licensed acquisition: the buyer can use the artifact, but protected source material remains creator-controlled through licensed knowledge references.
• Shared conversation rights: view only, fork conversation, or fork council and conversation.

Shared conversations use Snapshot semantics. A public conversation preserves the original member versions, orchestrator settings, council configuration, and conversation context so comparisons remain reproducible over time. Forks start from the captured snapshot unless the user explicitly upgrades to newer source versions later.

Public shared conversations can be exposed as Public council threads. A public council thread has a stable social sharing link, presents the visible council context, shows the featured question and council answer, and allows reply or fork behavior according to conversation acquisition rights. Replies can append to the public thread only when the publisher permits public participation; otherwise visitors fork the snapshot into their own owned copy.

Public templates and public council threads generate Social preview metadata from the underlying snapshot. The metadata includes Open Graph title, description, image, and canonical URL. The title should combine the council name with a short form of the question. The description should summarize the council answer. The image should be generated from the council name, member appearances, question, and answer state.

Public URLs should express domain resources rather than implementation IDs. The canonical featured council URL is /councils/featured/gods-cosmic-council-council-gods; the matching marketplace artifact URL is /marketplace/featured/gods-cosmic-council-council-gods. Council-created public threads should nest under their source council, for example /councils/featured/gods-cosmic-council-council-gods/threads/eternal-question-thread-eternal-question. Do not add top-level public thread shortcuts before launch; SEO, social, and product CTAs should use council, nested thread, or marketplace resource URLs.

Marketplace artifacts have a publication lifecycle: Draft, Submitted, Approved, Published, and Suspended. Paid artifacts cannot be purchased until published. Suspended artifacts cannot receive new purchases; prior-buyer access follows creator rights and platform policy.

Editing And Version Safety

A user can reuse the same council member across multiple councils or create a Member copy when they want a variant. Reuse preserves one member identity. Copying creates a new user-owned member with provenance such as source template, source member, version number, or timestamp.

A member's placement inside a specific council is a Council membership. The membership can define ordering and presentation overrides, but it does not replace member identity.

For deep edits, the app protects users from accidental cross-council changes. If a member is reused in multiple councils and the user edits its soul instruction, knowledge base, model override, or default appearance set, the app asks whether to:

• Update this reused member everywhere.
• Create a copy for this council.

Appearance, Knowledge, And Consensus

Council members have an Appearance set with assets grouped by four canonical states:

• Default: resting profile/card presence.
• Dormant: waiting, paused, inactive, or unavailable.
• Channeling: thinking, retrieving, self-processing, or composing.
• Conversing: actively speaking or responding.

MVP requires only a default asset and falls back to it for missing states. Later assets can include SVG, PNG, JPG, WebP, video, Three.js, or generated media.

Knowledge bases are member-owned. Free/open templates can duplicate knowledge as Bundled knowledge copies. Paid/protected templates can use Licensed knowledge references, where buyers can retrieve from protected material but cannot download or edit raw source documents.

Account-owned Knowledge documents are the RAG source objects. They can be uploaded, imported, or manually authored; processing creates searchable Knowledge chunks with optional embeddings. Knowledge bases connect members to documents/chunks while preserving sensitivity and licensing boundaries.

MVP consensus strategies are:

• Synthesis: integrates common threads and useful tensions into one answer.
• Deliberative Vote: summarizes each member's position and declares majority/minority views.
• Dialectic: surfaces conflicts, trade-offs, and a refined middle path.
• Advisory Brief: produces a concise recommendation with risks, assumptions, and next actions.
• Reflective Mirror: avoids a hard recommendation and returns questions, patterns, and invitations for contemplation.

The orchestrator uses one predefined strategy by default, with an optional advanced custom orchestrator instruction.

Model preferences resolve from broad to specific: account default, council default, member override, and orchestrator override. Production model calls route through Vercel AI Gateway model strings. UI code should not import provider-specific SDKs. The seeded default model is xai/grok-4.20-reasoning-beta, with openai/gpt-5.5 and openai/gpt-5.5-pro cataloged as OpenAI reasoning alternatives.

Current Foundation Slice

The first implementation slice is deterministic and persistence-ready. It defines TypeScript contracts and Supabase tables for councils, members, orchestrators, marketplace artifacts, acquisition rights, snapshots, public council threads, and social preview metadata. It also seeds a small marketplace, public thread, and deterministic SVG social preview so the product routes can be reviewed before payments, uploads, RAG, or live AI execution are added.

The current account/AI foundation slice adds account tenancy, model catalog/preferences, RAG document/chunk storage, persisted query runs, Supabase Auth magic-link entry, account-scoped council create/configure actions, and a reusable Council workbench fullstack component route. The workbench uses live AI through Vercel AI Gateway when configured, loads public-safe RAG snippets into member prompts when documents are linked, persists authenticated query runs, stores manual account knowledge notes as chunked RAG documents, clones starter members into newly created account councils, persists model preference records, and uses deterministic fallback when local credentials are absent.

The canonical seeded public thread is backed by the Gods Cosmic Council snapshot with Rumi, Meister Eckhart, Lao Tzu, and Dilgo Khyentse Rinpoche. The route-level public thread view derives from that snapshot so product copy, seed content, database content, and Open Graph metadata stay aligned.

During beta launch testing, the seeded Gods Cosmic Council marketplace artifact is free and publicly usable without authentication. Its original $12 one-time-purchase positioning should be struck through in UI copy where useful, with "Free during beta launch testing" as the visible price. Authentication is needed only for account ownership actions such as duplicating the artifact into a private workspace.

Cosmic Council — Technology Specification (technology.md)

Version: 1.3 Date: May 18, 2026 Status: Current Stack + Desired Future State (Updated with the React Router 7.15.1 patch alignment, Vercel-first compute boundary, AI Elements voice patterns, Vercel AI SDK, and Vercel AI Gateway) Purpose: This document captures the exact technology preferences, current stack decisions, rationale, architecture principles, and future evolution path for Cosmic Council. It serves as the technical companion to the technology-agnostic PRD.

1. Executive Technology Philosophy

Core Principle: Cosmic Council is a Vercel-first React Router application. The web framework owns product compute: SSR, loaders, actions, resource routes, AI orchestration, streaming, and user-facing server workflows should stay inside React Router on Vercel Fluid compute by default. Supabase is the complete backend platform for data, auth, storage, vectors, and realtime, but it is not the default home for product business logic. Supabase Edge Functions are an exception path only when the workload is database-adjacent, operationally simpler there, impossible on Vercel, or materially better than keeping the compute in React Router on Vercel.

Guiding Preferences (in order): 1. Functional programming patterns over OOP/classes (custom hooks, pure functions, composition, server functions). 2. Co-location of code (fullstack components + resource routes) wherever possible. 3. React Router SSR, loaders/actions, resource routes, and Vercel Fluid compute as the default compute surface. 4. Native streaming and data loading capabilities of the framework. 5. Vercel AI Gateway + Vercel AI SDK as the single source of truth for all model interactions (unified, observable, resilient access to every LLM provider). 6. AI Elements and voice-oriented AI Elements patterns as preferred building blocks for AI-native chat, streaming, agent, and voice interfaces when their shadcn/ui foundation fits the app. 7. Supabase for everything data-related (Postgres + pgvector + Storage + Auth + Realtime where it adds clear value). 8. Render.com exclusively for transactional email. 9. GitHub for source control and Vercel GitHub integration for CI/CD. 10. v0.app as the primary AI-powered UI component generator during development (via direct prompts or MCP integration where supported).

2. Current Technology Stack (May 2026)

Current package baseline after the route/living-docs review:

- react-router, @react-router/dev, @react-router/node, and @react-router/serve: 7.15.1 - @react-router/remix-routes-option-adapter: 7.15.1 - @vercel/react-router: ^1.3.0 - react / react-dom: ^19.2.6 - vite: ^7.3.3 - tailwindcss / @tailwindcss/vite: ^4.3.0 - typescript: ^6.0.3

Vite 8 is available in the wider ecosystem and is allowed by the current React Router peer range, but this project intentionally remains on Vite 7 until a dedicated build/deployment migration verifies devtools, Vercel builds, and Tailwind output together.

### 2.1 Frontend & Full-Stack Framework - Primary Framework: React Router v7+ (Framework Mode) — the successor to Remix Run v2+ - Route modules receive typed Route.ComponentProps; prefer component props for route-local loader data instead of untyped hooks. - Heavy emphasis on internal resource routes (/resources/*) for same-app data mutations, AI orchestration, and heavy logic. - Reserve external API routes (/api/*) for public contracts, webhooks, cron jobs, mobile clients, or third-party integrations. - Fullstack components — co-locate loader, action, and UI in the same route file whenever possible. - Strong preference for functional programming: custom hooks, pure functions, composition, server actions/functions. - Primary Compute Surface: Vercel SSR on Fluid compute for React Router server rendering, loaders, actions, resource routes, AI orchestration, and same-app server workflows. - Keep compute in the webapp framework by default. - Add separate compute only when profiling, provider limits, or platform constraints prove it necessary. - Architecture Boundary: Supabase owns backend capabilities; React Router on Vercel owns product compute. - Put normal CRUD, AI orchestration, token streaming, council synthesis, and same-app workflows in loaders, actions, resource routes, or server utilities. - Reach for Supabase Edge Functions only after the workload passes the exception test in section 3.3. - Future Evaluation: Migrate to Remix Run v3 once it has sufficient stability, documentation, community adoption, and clear migration path (target evaluation window: Q3–Q4 2026).

2.2 AI & Model Orchestration (Updated — Vercel AI Gateway + AI SDK)

Primary Layer: Vercel AI Gateway (https://vercel.com/ai-gateway) - Unified, production-grade gateway for all LLM providers (Anthropic, OpenAI, xAI/Grok, Google, Together, Fireworks, etc.). - Single endpoint and unified API key management. - Built-in features: automatic fallbacks & retries, load balancing, prompt caching, rate limiting, observability (traces, latency, cost per request), usage analytics, and cost guardrails. - All production traffic routes through the Gateway for reliability, cost control, and provider abstraction.

Client Library: Vercel AI SDK (https://ai-sdk.dev) - Official, actively maintained SDK (@ai-sdk/anthropic, @ai-sdk/openai, @ai-sdk/gateway, etc.). - Core/UI primitives for streaming text, structured output, embeddings, tools, agents, and generative interfaces. - First-class integration with Vercel AI Gateway through provider/model strings or explicit Gateway configuration when routing policy requires it. - Handles token-by-token streaming, tool calling, structured outputs, and error recovery. - All orchestration logic lives inside React Router resource routes / server actions on Vercel Fluid compute (no separate Node service, Vercel Edge Function, or Supabase Edge Function unless profiling or platform constraints justify it).

AI-Native UI Layer: AI Elements + Voice Patterns (https://elements.ai-sdk.dev) - Preferred component foundation for AI-native chat, streaming conversations, reasoning/source panels, prompt input, agent workflow surfaces, and voice interaction affordances. - Use AI Elements where its shadcn/ui registry model and component boundaries fit this app's design system. - Use voice-oriented AI Elements components and patterns, including speech input, voice selection, persona/listening/speaking states, and future voice-agent experiences, when they fit the local component system. - Adapt generated or registry components to React Router conventions, accessibility requirements, and the Cosmic Council visual system before merging.

Streaming Architecture: - Token-by-token streaming for every agent response and the final consensus is handled natively by: - React Router v7 Framework Mode server responses from actions/resource routes - Vercel AI SDK streamText (powered under the hood by Vercel AI Gateway) - This combination delivers the lowest possible latency, best error handling, and provider-optimized performance while staying 100% inside the user-specified framework.

Why This Combination Wins: - Vercel AI Gateway removes the need to manage multiple provider SDKs and keys. - ai-sdk.dev documentation is the single source of truth for implementation patterns. - Full observability and cost transparency out of the box — critical for a multi-agent product. - Seamless future-proofing when new models or providers are added.

### 2.3 Data, Auth, Storage & Vector Layer - Supabase (primary data platform) - Postgres 15+ with pgvector extension for embeddings and similarity search. - Supabase Storage for knowledge base files (PDF, MD, TXT, DOCX, etc.). - Supabase Auth (email magic links, Google, GitHub, etc.) with Row Level Security (RLS) on every table. - Supabase Realtime subscriptions — used selectively for: - Live UI updates when new messages are saved (multi-tab sync or future multi-user). - Council template changes. - Notification of new shared councils. - Not used for primary AI token streaming (React Router + Vercel AI SDK + Gateway is superior for this workload).

### 2.4 Deployment, Hosting & Infrastructure - Vercel — primary hosting platform - Framework Mode native support. - @vercel/react-router/vite preset configured in react-router.config.ts. - React Router SSR and route handlers run on Vercel Functions with Fluid compute as the default execution model. - Keep application compute in React Router on Vercel before considering any separate backend function runtime. - Preview deployments, analytics, and GitHub integration. - Native integration with Vercel AI Gateway (zero-config routing for production traffic). - Supabase Edge Functions — fallback only - Use only when absolutely necessary or clearly much better than Vercel-hosted React Router compute, such as Supabase-local triggers, direct database-adjacent workflows, or platform constraints that Vercel cannot satisfy cleanly. - Do not use for primary AI orchestration, token streaming, council synthesis, normal CRUD workflows, or same-app UI actions. - Render.com — transactional email only (invites, password resets, council share notifications, weekly digests). - GitHub — version control, issues, CI/CD via Vercel GitHub App.

### 2.5 Supporting Libraries & Patterns (Recommended) - TypeScript (strict) - Tailwind CSS 4 + custom cosmic-themed components. - Tailwind is integrated through @tailwindcss/vite; avoid adding legacy PostCSS/autoprefixer wiring unless a specific compatibility issue requires it. - shadcn/ui or Radix primitives may be introduced when a real component need justifies them; AI Elements is preferred for AI-native interface components built on that foundation when it fits the actual installed component system. - Zod should be preferred for route action payloads, structured AI outputs, and API boundary validation. - React Hook Form is optional; prefer native <Form>, useFetcher, and route actions until form complexity justifies another dependency. - Avoid TanStack Query for route-owned server state; React Router loaders/actions are the source of truth for URL-addressable data. - Framer Motion may be introduced for subtle, purposeful animations after the core flow is stable. - react-markdown + remark-gfm + syntax highlighting may be introduced when rich rendered Markdown is product-critical. - date-fns or dayjs may be introduced when date formatting outgrows built-in Intl APIs.

2.6 Development & UI Prototyping Tools (New)

v0.app (https://v0.app) — Vercel’s AI-powered UI generator - Primary tool for rapidly creating beautiful, accessible, production-ready React components. - Used extensively to generate: - AgentCard, CouncilStream, ConsensusBox, ThinkingPanel, etc. - Layouts, empty states, modals, and streaming UI patterns that match the sacred cosmic aesthetic (deep navy, soft gold, elegant serif accents, generous whitespace). - Workflow: Prompt v0 with references to the Design & Experience Principles from prd.md + current Tailwind/shadcn setup. - MCP Integration (optional but recommended): If the coding environment (Cursor, Claude Desktop, Windsurf, etc.) supports the Model Context Protocol (MCP), connect v0 directly for seamless, context-aware component generation without leaving the IDE. - This dramatically accelerates the “beautiful streaming UI” requirement while maintaining pixel-perfect alignment with the product vision.

AI Elements + Voice-Oriented Patterns (https://elements.ai-sdk.dev) - Preferred starting point for AI-native interface controls once the project adopts shadcn/ui-compatible component workflows. - Use for chat, conversation, message, reasoning, source, prompt input, task/workflow, speech input, voice selector, and persona/listening/speaking UI patterns. - If AI Elements does not fit the local Tailwind/shadcn setup for a specific component, implement a local component that follows the same interaction pattern instead of forcing the dependency. - Treat all installed components as local source code: adapt styling, accessibility, file placement, and React Router integration before shipping.

3. Architecture Principles & Decisions

### 3.1 Streaming Architecture Decision (Explicit & Updated) Primary AI response streaming (token-by-token per agent + consensus) is handled exclusively by: - React Router v7 Framework Mode streaming responses in actions/resource routes - Vercel AI SDK streamText (routed through Vercel AI Gateway) - Vercel SSR/Functions on Fluid compute as the preferred runtime surface

Rationale: This combination delivers the lowest latency, best error handling, provider-optimized streaming, full observability, automatic fallbacks, and keeps all logic inside the framework the user specified. Vercel AI Gateway adds production-grade resilience without any extra code.

Supabase Realtime is used only for secondary, lower-frequency updates (message persistence sync, template changes, notifications). Using Supabase Realtime for primary token streaming would add unnecessary complexity, latency, and cost.

### 3.2 Orchestration Location All council query logic, parallel agent calls, RAG retrieval, and consensus synthesis live inside a React Router internal resource route (e.g., app/routes/resources+/query.route.ts). No separate backend microservice. No Supabase Edge Function unless it is absolutely necessary or clearly much better for the specific workload. All model calls are routed through Vercel AI Gateway.

### 3.3 Compute Boundary Decision Rule Use React Router on Vercel for: - SSR, loaders, actions, and resource routes. - AI orchestration, agent coordination, council synthesis, and streaming responses. - CRUD workflows and app-owned business logic. - User-facing request/response compute.

Use Supabase for: - Postgres, RLS, Auth, Storage, pgvector/retrieval data, and durable application data. - Realtime only for secondary sync, collaboration, notifications, or persistence updates.

Use Supabase Edge Functions only for: - Database-adjacent background jobs or trigger-like workflows that are cleaner near Supabase. - Workloads Vercel cannot handle cleanly because of platform limits. - Cases where measurement or operational simplicity proves Supabase is materially better.

### 3.4 Data Model Philosophy - Keep the schema relational and aligned with product language: councils, council members, council memberships, council orchestrators, marketplace artifacts, snapshots, public council threads, and social previews are first-class tables. - Model ordered council membership as rows, not arrays, so reused council members, council-specific presentation overrides, and deep-edit safety can be enforced cleanly. - Store public shared conversations as immutable snapshots so public threads and marketplace artifacts remain reproducible over time. - Use pgvector + cosine similarity for future RAG chunks once uploads and embeddings are implemented. - Keep knowledge ownership member-scoped: each council member owns one or more knowledge bases; paid/protected templates can expose licensed knowledge references without exposing raw source documents.

### 3.5 Cost & Performance Guardrails (MVP) - Per-user daily/weekly query limits (soft + hard) — enforced and visible via Vercel AI Gateway usage data. - Smart context window management (truncate intelligently or summarize long knowledge bases). - Prompt caching enabled via Vercel AI Gateway where safe. - Transparent per-query token usage + estimated cost display. - Automatic fallback to cheaper/faster models on rate limits or errors.

4. Recommended Project Structure (React Router 7 Framework Mode)

app/
├── routes/
│   ├── _index/
│   │   └── _route.tsx                # Landing + login / onboarding
│   ├── councils+/
│   │   ├── _index.tsx                # My Councils + Public Gallery
│   │   ├── new.tsx                   # Create Council flow
│   │   └── $councilId.tsx            # Council detail + query UI (main magic)
│   ├── resources+/                   # Internal resource routes, called by this app
│   │   ├── agents.route.ts
│   │   ├── councils.route.ts
│   │   ├── query.route.ts            # Main council query endpoint: streaming + orchestration via Vercel AI Gateway
│   │   └── upload-knowledge.route.ts
│   └── api+/                         # External/public API contracts only
│       └── v1+/
│           └── councils.route.ts
├── components/
│   ├── AgentCard.tsx                 # (generated via v0.app)
│   ├── CouncilStream.tsx             # Streaming per-agent + consensus UI (v0.app generated)
│   ├── ConsensusBox.tsx
│   └── ThinkingPanel.tsx
├── datastores/
│   └── supabase/
│       └── client.server.ts
├── services/
│   └── vercel-ai.server.ts           # Gateway + SDK wrappers, provider config, cost tracking
├── lib/
│   └── rag.ts                        # Chunking + embedding helpers (pure functions)
├── types/
│   └── index.ts
├── root.tsx
└── entry.server.tsx / entry.client.tsx (standard)

5. Supabase Database Schema (Current Recommendation)

The current schema is implemented in supabase/migrations/20260518005000_create_council_marketplace_schema.sql and summarized in specs/development/database.md.

Current foundation tables:

• profiles
• councils
• council_members
• council_orchestrators
• council_memberships
• appearance_sets
• appearance_assets
• knowledge_bases
• snapshots
• snapshot_members
• snapshot_member_knowledge_bases
• snapshot_messages
• marketplace_artifacts
• public_council_threads
• social_previews

Every public-schema table enables Row Level Security. Public visitors can read published marketplace artifacts, public council/thread records, public-safe member/appearance/knowledge summaries, and published snapshots required by public threads. Authenticated users can manage owned records through owner_profile_id or creator_profile_id. The deterministic seed in supabase/seed.sql creates the Gods Cosmic Council, its four members, licensed-reference knowledge summaries, marketplace artifacts, the eternal-question snapshot, and social preview metadata.

Future migrations should add uploads, document chunks, embeddings, usage metering, payments, and live conversation persistence when those product workflows are implemented. Do not reintroduce an agent_ids array model; ordered council membership belongs in council_memberships so member reuse, provenance, and presentation overrides remain queryable and enforceable.

6. Desired / Future Technology Evolution

### Near-Term (v1 – 3–5 Months) - Full utilization of Vercel AI Gateway advanced features: prompt caching, custom routing rules, detailed usage dashboards, automatic cost alerts. - Deeper Vercel AI SDK features (structured outputs, tool calling if added to agents later). - AI Elements and voice-oriented AI Elements adoption for chat, streaming, and voice UI patterns once shadcn/ui-compatible components are introduced. - Supabase Edge Functions only for workloads that are impossible or materially worse in React Router on Vercel. - Advanced pgvector indexes (HNSW) and hybrid search (keyword + vector). - Better chunking strategies (semantic, hierarchical, agent-specific).

### Medium-Term (6–12 Months) - Evaluation of Remix Run v3 for potential migration (if stable and beneficial). - Supabase Realtime for real-time collaborative council sessions. - Vercel AI SDK + Gateway for fine-tuned or self-hosted models (via custom providers). - Vercel-hosted long-running synthesis or heavy RAG pipelines first; Supabase Edge Functions only where they are proven necessary or clearly superior. - v0.app + MCP for even faster component iteration and design-system consistency.

### Long-Term Aspirations - Self-hosted / on-premise option (Docker + Supabase self-hosted + local models via Ollama or vLLM, still fronted by Vercel AI Gateway where possible). - Agent-to-agent protocol standardization (A2A, MCP, etc.) if industry converges. - Voice + multimodal pipeline (separate from core council experience).

7. Constraints & Non-Negotiables

• All AI orchestration logic must remain inside React Router v7 resource routes / server actions.
• Vercel SSR on Fluid compute is the default runtime for framework-owned compute.
• All production model calls must route through Vercel AI Gateway for reliability, observability, cost management, and provider abstraction.
• No separate monolithic backend service unless performance profiling proves it necessary.
• Vercel AI SDK (configured for Gateway) is the single source of truth for model calls (no direct provider SDK calls in production code).
• Supabase is the single source of truth for data, auth, storage, vectors, and realtime where needed.
• Supabase Edge Functions are allowed only as an exception when the workload is database-adjacent, operationally simpler there, impossible on Vercel, or materially better than keeping compute in React Router on Vercel.
• Render.com is used only for email (no other services on Render).
• Functional programming patterns preferred; OOP only when unavoidable for complex state machines.
• All environment variables and secrets managed via Vercel (never client-side).
• v0.app is the preferred method for UI component generation during active development.

8. Open Technical Questions (to Resolve During Implementation)

1. Exact chunk size / overlap strategy per agent type (spiritual texts vs technical documents)?
2. Should we support user-provided API keys (BYOK) from day one or later (Gateway makes this easier)?
3. Best default moderator model and synthesis prompt for highest user satisfaction?
4. How to gracefully handle partial failures (one agent times out or errors) — Gateway fallbacks help here.
5. Caching strategy for RAG results and common queries (leverage Gateway prompt caching)?
6. When to introduce HNSW indexes vs current IVFFlat?
7. Optimal way to expose Vercel AI Gateway usage analytics to end users (per-council cost dashboard)?

This technology.md document is the living technical spec. It will evolve as we learn from implementation and as the ecosystem (React Router, Vercel AI Gateway + AI SDK, Supabase, Remix, v0) matures.

All decisions are made in service of the product vision defined in prd.md while strictly honoring the user’s stated technology preferences and the powerful capabilities of the Vercel AI ecosystem (Fluid compute + Gateway + AI SDK + AI Elements + voice patterns + v0.app).

Cosmic Council Technology Specification – Version 1.2 – May 17, 2026

Public Council Thread Sharing

This spec records the design direction from the first public council view sketch. It defines how a public council template or shared conversation should work when visited through a social sharing link.

Reference mockup asset: specs/design/mockups/public-council-thread-sketch.png

Core Experience

A public council template or shared conversation can be visited through a stable social sharing URL. The page presents a council chamber: visible council members around the council space, member labels, member configuration affordances, an orchestrator/consensus strategy control, the current question, the council answer, and a reply input.

For public conversations, the page behaves like a thread:

• The first visible exchange is the shared question and generated council answer.
• Visitors can inspect the public council/member setup according to creator rights.
• If replies are permitted, a visitor can ask a follow-up in the same public thread or fork into their own owned copy.
• The thread preserves snapshot semantics so the shared answer remains comparable over time.

Social Sharing Link

Public templates and public/shared conversations need canonical social URLs. A shared URL should be suitable for posting on social networks, newsletters, chat, and websites.

When a social post links to a public council thread:

• The link opens the public council thread view.
• The thread shows the relevant council, current question, and latest or featured council answer.
• Reply behavior follows the shared conversation's acquisition rights and visibility settings.
• Visitors who are not allowed to mutate the public thread can fork the conversation into an owned copy when rights permit.

Generated Social Preview Metadata

Public council threads should generate Open Graph metadata from the conversation snapshot.

Generated metadata should include:

• OG title: council name plus a short form of the current question.
• OG description: concise summary of the council answer or consensus.
• OG image: generated visual preview based on the council name, member appearances, question, and answer state.
• Canonical URL: stable public URL for the template or conversation snapshot.

The OG image and description should be regenerated when a public conversation is first shared, when the featured answer changes, or when the publisher explicitly refreshes the social preview. Snapshot-based public conversations should keep previously generated previews stable unless intentionally refreshed.

UI Requirements From The Sketch

The first implementation should preserve the sketch's functional ideas, not its exact visual style:

• Council members are visually distinct and named.
• The central council space frames the active question and answer.
• The orchestrator/consensus strategy is visible as a control or label, not as another speaking member.
• Member configuration details such as soul instruction, model, and knowledge access can be progressively disclosed.
• The reply input is prominent and clearly tied to the public thread.
• The design must work responsively; the chamber composition can simplify on mobile.

MVP Boundaries

MVP should implement the public route, public-thread metadata contract, and a deterministic generated preview image before building full AI-generated images. The first renderer can use a simple SVG template derived from the conversation snapshot, then later evolve into a richer visual or generated-image pipeline.

Homepage SaaS Landing Page And Public Council Demo

The homepage should be a fully fledged SaaS landing page for Cosmic Council, anchored by a public, ready-to-try council experience. The Gods Cosmic Council is the default live-looking example. It should be public for now and must tell visitors that the demo uses prepared deterministic responses or the configured workbench fallback when live AI execution is unavailable.

Experience Shape

The first viewport presents a full-bleed product hero inspired by the provided cosmic council sketches and by modern SaaS/product pages:

- A clear promise for the whole service: councils are configurable multi-agent products, not loose prompt packs. - Product name, account registration, demo, and marketplace calls to action, exposed through the global app navbar and hero calls to action rather than a homepage-only primary nav. - A large visual council stage or background with energetic member appearances. The hero should use one primary visual system at a time. The current homepage hero uses the generated council artwork as the background image with restrained color overlays; particle/Three.js visuals are reserved for council preview surfaces so the first viewport does not stack competing animated treatments. - A concise explanation of account workspaces, marketplace artifacts, public threads, model/provider configuration, knowledge bases, and social sharing. - A footer with company/legal links.

The visual direction should feel modern and ready to use: high-contrast, refined editorial SaaS composition, strong color contrast, crisp Tailwind utility styling, 8px-radius controls, and no old dashboard/card-heavy marketing look. It can use generated reference artwork and CSS/Three.js effects, but the product and council experience should remain the primary first-viewport signal.

The SaaS page should include enough sections for a serious product decision:

• Persona/use-case positioning.
• The core problem and product wedge.
• Interactive public council preview.
• Feature/platform module matrix.
• Marketplace and provenance section.
• Clear account/registration CTA.
• Launch packaging or pricing-style entry points.
• FAQ and trust/status language that does not overclaim incomplete features.

The selectable example councils should sit below the hero as product-card tabs that switch one featured interactive council stage guided by the rough chamber sketch:

- Three product-card tabs for the selectable example councils should sit outside and above the chamber. They should read as marketplace/product previews and switch the selected council stage/config/content. - Council members should appear above the chamber/table in a loose arc with name labels, using modern energetic silhouettes or generated/particle appearances rather than plain cards. - The conversation should sit inside a central chamber/table body with a visible focal point such as a flame, portal, or energy well. - A conventional responsive chat panel should sit below the council stage on desktop and mobile. The panel should have a fixed conversation header, scrollable message history, and bottom composer. User questions, streamed member perspectives, and final synthesis should all appear inside this same chat transcript, with the transcript auto-scrolling as chunks arrive. - Visible member chips and current council identity near the conversation surface. - Model/setup metadata, public-demo notice, and secondary links should default to collapsed disclosure controls or dropdown-like panels inside the stage so they do not compete with the primary council/chat hierarchy. - Direct links to the full marketplace listing, the selected council product page, a public thread, and the published living docs. - The flagship public council and marketplace artifact should use domain-readable URLs, not implementation IDs: /councils/featured/gods-cosmic-council-council-gods for direct public use and /marketplace/featured/gods-cosmic-council-council-gods for acquisition and artifact details. Council-created public threads should nest under the council, for example /councils/featured/gods-cosmic-council-council-gods/threads/eternal-question-thread-eternal-question.

Landing-page copy should follow a clear desire/mechanism/proof/conversion structure:

- Name the user's felt problem: single-chatbot answers collapse too quickly when the question needs multiple perspectives. - Present the unique mechanism: named council members with soul instructions, appearance states, knowledge bases, model choices, and an orchestrator strategy. - Show proof through the ready-to-try public Gods Cosmic Council demo and marketplace artifacts. - Convert through clear next actions: try the demo, inspect the marketplace artifact, share a public thread, or create a custom council. - Free beta artifacts should be usable publicly without authentication. Login is required only for account-scoped actions such as duplicating into a private workspace or persisting private runs.

Demo Councils

MVP homepage tabs should include:

- Gods Cosmic Council: the default spiritual/philosophical public demo. - Founder Strategy Council: a business strategy example for planning and trade-offs. - Research Synthesis Council: a knowledge/research example for evaluating competing interpretations.

Only Gods Cosmic Council needs marketplace/product depth in this slice. The other two examples can be deterministic preview demos that illustrate the selection pattern and future template surface.

Boundaries

The homepage demo is not the same as a live shared conversation. It is a Public council demo: a seeded interactive preview plus the reusable workbench where configured. Until streaming and citations land, it must avoid implying that every response is streamed with full source panels.

When live AI execution lands, the same first-viewport UI can connect to the council query route and replace deterministic responses with streamed member responses plus the orchestrated synthesis.

Architecture

Canonical architecture patterns and decisions for Cosmic Council.

Overview

Cosmic Council is a React Router framework-mode application with SSR enabled and Vercel as the primary deployment target. React Router SSR, loaders, actions, resource routes, AI orchestration, streaming, and user-facing server workflows should run on Vercel Functions with Fluid compute by default. Supabase is the complete backend platform for data, auth, storage, vectors, and realtime, but React Router on Vercel owns product compute. The application should keep user-facing UI in route modules and components, keep server-only integration logic out of client bundles, and use documented specs as living source material for future work.

Directory Structure

• app/routes/ contains route modules discovered through remix-flat-routes.
• app/routes/resources+/ is reserved for internal resource routes called by the app's own UI.
• app/routes/api+/ is reserved for external/public API contracts, versioned webhooks, cron endpoints, and third-party clients.
• app/datastores/ owns app data integrations such as Supabase, Redis, or object storage.
• app/services/ owns external APIs the app calls, including AI providers, email, or payment services.
• app/lib/ contains pure utilities with no network calls or side effects.
• app/features/councils/ contains the current council domain, marketplace rules, deterministic seed data, and public thread helpers until the Supabase-backed datastore is wired in.
• app/welcome/ contains starter template assets that are no longer part of the active route surface.
• app/app.css contains global styling, including Tailwind CSS.
• supabase/migrations/ contains database schema migrations.
• supabase/seed.sql contains deterministic local seed content for the current foundation slice.
• specs/ contains canonical product, architecture, technology, implementation, and process documentation.
• docs/ is reserved for external references and internal notes that are not canonical product specs.

The current public route/page surface is cataloged in specs/development/routes.md.

Account And Workbench Architecture

The reusable council UI is the Council workbench. It lives as a fullstack component route at app/routes/resources+/council-workbench.route.tsx:

- loader advertises supported workbench intents. - action handles same-app council operations: streamed or JSON live/deterministic querying, authenticated account-scoped council creation, and authenticated council configuration updates. - CouncilWorkbench is a named UI export that product pages can embed with route-specific initial messages, council labels, disclosure text, placeholder copy, and height constraints. - CouncilWorkbenchManager is a named UI export that account pages can embed for the current create/configure control surface.

Pages should embed the workbench rather than copying query/configuration forms. This keeps validation, AI execution, persistence, and account checks centralized while allowing the homepage, marketplace pages, council detail pages, and future dashboards to show the same council surface.

Auth and account management use route pages:

- /auth/login sends Supabase magic links. - /auth/callback exchanges Supabase auth codes for SSR cookies. - /account lists and creates account workspaces and exposes the account council create/configure manager. - /resources/auth.logout signs out through a same-app resource action.

AI Architecture

AI features should use a layered integration:

1. Route actions/loaders or server utilities receive product requests and enforce app-level validation.
2. AI SDK (ai) performs model orchestration, streaming, structured output, and tool calling.
3. Vercel AI Gateway provides model/provider routing, centralized credentials, fallback strategy, usage tracking, and observability.
4. AI Elements and voice-oriented AI Elements patterns provide preferred UI building blocks for chat, streaming, reasoning/source panels, prompt input, speech input, voice selection, and persona/listening/speaking states when their shadcn/ui foundation fits the app.
5. Client components consume sanitized server responses or streams; provider credentials never cross into browser code.

When v0 is used for UI generation, treat its output as a design and implementation draft. Integrate only the pieces that match this app's React Router conventions, Tailwind setup, accessibility expectations, and existing component boundaries.

Data Flow

• Browser requests enter React Router route modules.
• Loaders provide read data for SSR and client transitions.
• Actions handle mutations and server-owned workflows.
• AI calls originate on the server, run in React Router on Vercel by default, flow through AI SDK, and route through Vercel AI Gateway unless a specific feature explicitly requires a direct provider integration.
• Council query runs are persisted through Supabase when the visitor is authenticated and belongs to an account; anonymous or unconfigured environments receive deterministic fallback responses without persistence.
• Streaming AI responses should be exposed through route-level server responses that preserve backpressure and avoid leaking secrets.
• Supabase Edge Functions are a fallback only when the workload is database-adjacent, operationally simpler there, impossible on Vercel, or materially better outside React Router on Vercel.
• Supabase Postgres persists councils, council members, ordered memberships, orchestrators, appearance sets, knowledge summaries, snapshots, marketplace artifacts, public council threads, and social preview metadata.
• Supabase Postgres also persists account tenancy, account memberships, model preferences, RAG documents/chunks, and council query runs.
• Public marketplace and public thread reads are backed by RLS policies that expose only published/public records and the public-safe related rows needed to render them.

Key Patterns

• Prefer server-owned integrations for AI, credentials, and external APIs.
• Keep internal same-app endpoints under /resources/*; use /api/* only when the endpoint is a stable external contract.
• Keep route modules thin when behavior grows; extract reusable server logic under app-owned modules.
• Preserve the import direction routes -> services -> datastores -> lib.
• Keep database schema changes in Supabase migrations and reflect product-facing schema decisions in specs/development/database.md.
• Use AI SDK abstractions before writing provider-specific model code.
• Prefer AI Elements and voice-oriented AI Elements patterns before inventing custom AI-native interface primitives, but do not force the dependency when a local component better fits the current Tailwind/shadcn setup.
• Keep model IDs, fallback policy, and operational assumptions documented with the feature that uses them.
• Review generated code from v0 before merging; generated code must not bypass local architecture, testing, or documentation standards.

Database Contract

Cosmic Council uses Supabase Postgres as the durable system of record for accounts, memberships, councils, council members, marketplace artifacts, RAG knowledge, model preferences, snapshots, public council threads, query runs, and social preview metadata.

Current migrations:

• supabase/migrations/20260518005000_create_council_marketplace_schema.sql: marketplace/domain/public-thread foundation.
• supabase/migrations/20260518101950_create_accounts_rag_models_query_runs.sql: account tenancy, AI model catalog/preferences, RAG document/chunk foundations, and persisted council query runs.
• supabase/migrations/20260518104333_restrict_public_rls_auto_enable.sql: revokes public API role execution on the existing public.rls_auto_enable() security-definer helper flagged by Supabase advisors.

Deterministic MVP content lives in supabase/seed.sql.

Security Baseline

Every table in the public schema enables Row Level Security. Public visitors can read published marketplace artifacts, public councils, public thread snapshots, public thread records, social previews, active model catalog rows, and the member/appearance/knowledge summaries needed to render those public surfaces.

Authenticated users operate through profiles and account memberships. Account-scoped records are visible or mutable only to account members with the required role. Do not authorize account behavior from user-editable metadata. Use Supabase Auth user identity plus account_memberships and RLS.

The seed content is curated platform content with null owner profile IDs. It is expected to be applied by the database owner or service role during local setup or controlled deployment, not by a public client.

Core Tables

• profiles: Auth-linked creator/user profiles and creator type.
• accounts: tenant/workspace boundary for private councils, RAG documents, model preferences, query runs, usage policy, and future billing.
• account_memberships: authenticated profile membership in accounts with owner/admin/editor/viewer roles.
• councils: account-owned, user-owned, or platform-seeded councils with visibility and model default.
• council_members: reusable account-owned or platform-seeded council members with soul instruction, optional model override, and provenance fields.
• council_orchestrators: One orchestrator per council with consensus strategy and optional custom instruction.
• council_memberships: Ordered placement of members inside a council.
• appearance_sets and appearance_assets: Member appearance states and media references.
• knowledge_bases: Member-owned knowledge references or bundled copies, with public-safe source summaries only.
• knowledge_documents: account-owned uploaded/imported/manual source documents with processing status and sensitivity.
• knowledge_document_chunks: searchable document chunks with optional vector(1536) embedding, token estimate, and public-safe excerpt.
• knowledge_base_documents: join table connecting member knowledge bases to account documents.
• ai_model_catalog: Gateway-routed text and embedding model registry.
• model_preferences: account, council, member, and orchestrator scoped model settings.
• council_query_runs: persisted council question execution metadata, mode, model, strategy, warning, token estimate, and cost placeholder.
• council_query_messages: user/member/consensus messages created by a query run.
• snapshots, snapshot_members, snapshot_member_knowledge_bases, and snapshot_messages: Immutable captured council/conversation state for reproducible shared conversations.
• marketplace_artifacts: Council templates, council member templates, and shared conversation artifacts with lifecycle status, purchase model, acquisition mode, creator rights, and trust summary.
• public_council_threads: Stable public thread URLs backed by snapshots.
• social_previews: Generated Open Graph title, description, image path, and canonical path for public threads.

Seed Content

The MVP seed inserts:

- The Gods Cosmic Council. - Four council members: Rumi, Meister Eckhart, Lao Tzu, and Dilgo Khyentse Rinpoche. - Licensed-reference knowledge base summaries for each member. - Default particle-style appearance assets for each member. - A snapshot-stable public conversation for the eternal-question thread. - Three published marketplace artifacts: Gods Cosmic Council, Lao Tzu member, and The Eternal Question conversation. During beta launch testing, the Gods Cosmic Council artifact is free, forkable, and publicly usable without authentication. - One hidden draft artifact used to verify marketplace filtering. - A public thread and matching deterministic social preview metadata with canonical path /councils/featured/gods-cosmic-council-council-gods/threads/eternal-question-thread-eternal-question. - An AI model catalog seed for selected AI Gateway text and embedding models. The default text model is xai/grok-4.20-reasoning-beta; GPT-5.5 and GPT-5.5 Pro are cataloged alternatives.

The deterministic seed has been applied to the remote cosmic-council project and remains idempotent through insert ... on conflict statements. Public marketplace and public-thread loaders read these Supabase rows first and fall back to the local TypeScript seed when Supabase is unavailable.

Boundary

This schema now covers the durable foundations for account tenancy, account-scoped council creation/configuration, model routing, manual knowledge-note document/chunk storage, RAG snippet loading for prompts, and live query-run persistence. It does not yet implement file upload processing, embedding generation jobs, semantic retrieval ranking, payments, account billing, or usage metering enforcement. Those should be added in focused migrations when the corresponding route actions and background workflows are implemented.

Environment And Tooling

Runtime Supabase access uses SUPABASE_URL and SUPABASE_PUBLISHABLE_KEY (or SUPABASE_ANON_KEY as a compatibility fallback). Supabase SSR cookies are handled with @supabase/ssr, and server authorization should call auth.getUser() before account-scoped operations.

The repo includes a Supabase MCP server in .mcp.json scoped by SUPABASE_PROJECT_ID, plus local CLI usage through npx supabase. Remote database operations must only target the Supabase project named cosmic-council, currently project ref miridqqphvrbmnrzowdy. Run npm run supabase:project:check before remote type generation, linking, migration application, or direct SQL. The guard maps SUPABASE_PERSONAL_ACCESS_TOKEN to SUPABASE_ACCESS_TOKEN for CLI project discovery. If the authenticated token cannot see a project named cosmic-council or the env project ref does not match it, do not link or apply migrations remotely.

The remote cosmic-council migration history was synced on May 18, 2026. Supabase advisors are clear of the public executable security-definer warning after the revoke migration. Remaining advisor output is limited to performance warnings for multiple permissive RLS policies on tables that currently support both owner-based and account-membership-based access paths.

Webapp Route Catalog

This catalog records the current React Router Framework Mode route surface for Cosmic Council. It is the public implementation map that keeps product routes, living docs, and route-module conventions aligned.

Reviewed Stack

Route behavior was reviewed against the current app structure and the current React Router Framework Mode documentation on May 18, 2026.

- React Router route modules define page components, loaders, metadata, error boundaries, and resource responses from files referenced by app/routes.ts. - This repo uses remix-flat-routes through @react-router/remix-routes-option-adapter, so + folders create path nesting and route modules are discovered below app/routes/. - Vercel deployment uses @vercel/react-router/vite in react-router.config.ts, which is the expected preset for React Router on Vercel SSR and Fluid compute. - Tailwind CSS 4 is integrated through @tailwindcss/vite, matching the current Vite integration guidance.

Current Route Surface

Route Architecture Notes

- The root route renders the global product navigation before the active route outlet, so auth, account, marketplace, council, living-docs, and error pages always expose a way back to the main product surfaces. Route pages should not add a second primary navbar; use page-local navigation only for secondary resource context. - /living-docs is intentionally a route-page family, not an API endpoint. The index route redirects to the preferred locale and the locale routes render the reader UI. - The living-docs publisher imports raw Markdown statically from explicit manifest entries. Do not replace this with filesystem globbing or runtime directory reads in production code. - Internal same-app mutation or streaming endpoints should be added under app/routes/resources+/ as *.route.ts files when council querying or uploads become interactive. - Public canonical product/resource URLs should use domain language before implementation IDs. The flagship beta council uses /councils/featured/gods-cosmic-council-council-gods; the marketplace artifact uses /marketplace/featured/gods-cosmic-council-council-gods; council-created threads use /councils/featured/gods-cosmic-council-council-gods/threads/eternal-question-thread-eternal-question. - Reusable UI with server behavior should use a fullstack component route under app/routes/resources+/ with a named UI export and colocated loader/action. app/routes/resources+/council-workbench.route.tsx and app/routes/resources+/marketplace-acquisition.route.tsx are the canonical examples. - External contracts, webhooks, cron endpoints, and third-party API surfaces should be added under app/routes/api+/, preferably versioned. - Server-only shared logic belongs under app/datastores/, app/services/, or app/lib/ according to ownership and side effects; do not put .server.ts route modules inside + route folders.

Data Boundary Notes

The public marketplace and public thread surfaces read Supabase first and retain deterministic seed fallback for local/offline resilience. The Council workbench also attempts Supabase reads and persistence when configured, falls back to seed council data when the database is unavailable, and uses Vercel AI Gateway for live answers when credentials are present.

Feature Implementation Status

This document is the implementation ledger for the living docs. It maps the product/spec sections to current code, database, route, and verification state. Use it before claiming a feature is complete.

Status Legend

- [x] Implemented: Code exists, docs match behavior, and verification has run. - [~] Partial: A usable foundation or narrow slice exists, but the full spec is not complete. - [ ] Missing: The spec is documented but no meaningful implementation exists. - [!] Blocked: Implementation depends on a missing decision, credential, service, or external prerequisite.

Foundation And Publishing

Public Product Surface

Accounts And Auth

Council Configuration

Query And AI

Knowledge And RAG

Sharing, Forking, And Marketplace

Operations, Trust, And Launch

Verification Baseline

Run these before marking a feature row [x]:

npm run docs:living:check
npm run typecheck
npm run test:run
npm run build

For Supabase changes, also run:

npm run supabase:project:check
npx dotenv -c -- sh -c 'SUPABASE_ACCESS_TOKEN="${SUPABASE_ACCESS_TOKEN:-$SUPABASE_PERSONAL_ACCESS_TOKEN}" npx supabase migration list'
npx dotenv -c -- sh -c 'SUPABASE_ACCESS_TOKEN="${SUPABASE_ACCESS_TOKEN:-$SUPABASE_PERSONAL_ACCESS_TOKEN}" npx supabase db advisors --linked -o json'

Use HTTP or browser smoke checks for every changed route/resource surface.

Implementation Plan

Roadmap for implementation tasks. This document outlines the phased approach to building features defined in the PRD.

Current Phase

Council domain, marketplace, account tenancy, RAG/model foundation, and council workbench implementation, with Supabase persistence contracts in place for review.

Feature-by-feature implementation truth now lives in specs/development/feature-status.md. Update that checklist whenever product behavior, route contracts, database contracts, AI behavior, or verification status changes.

Upcoming Work

Phase 0: Living Product Foundation

• Replace the starter welcome screen with a modern public council demo that uses large selectable example councils, a ready-to-try deterministic chat interface, visible public-demo disclosure, and links into marketplace, public threads, and living docs.
• Define the MVP information architecture for councils, agents, conversations, templates, and knowledge bases.
• Define the MVP information architecture for marketplace artifacts, one-time acquisition, curated creators, creator rights, and licensed knowledge references.
• Define public council thread URLs, reply/fork behavior, and generated social preview metadata for public templates and shared conversations.
• Implement the first typed marketplace foundation with seed artifacts, Supabase schema/seed content, public council thread routing, and deterministic social preview metadata/image generation before adding payments, uploads, RAG, or live AI execution.
• Convert the Gods Cosmic Council appendix in specs/prd.md into seed data requirements.
• Decide the initial public template gallery, marketplace listing surface, duplication workflow, and paid acquisition boundaries.

Phase 1: Core Council Experience

• Build the council detail/query route as the main product experience.
• Implement agent and council creation/editing with route actions and server-side validation.
• Implement council default model settings plus per-member and per-orchestrator model overrides.
• Implement council orchestrator configuration with predefined consensus strategies and optional custom orchestrator instruction.
• Implement the first internal /resources/query route for parallel agent responses and synthesis.
• Stream per-agent responses and final consensus through React Router server responses on Vercel Fluid compute and Vercel AI SDK streamText.
• Add visible source/thinking panels with progressive disclosure, using AI Elements where it fits the local component system and local components where they fit better.
• Persist conversations, messages, and branch/fork metadata.
• Add a public council thread route for shared conversations with snapshot-stable question, answer, member context, and reply input behavior.
• Connect the homepage public council demo to the real council query route when AI execution is available, replacing deterministic responses with streamed member responses and orchestrated synthesis.
• Optimize account/owner RLS policies to reduce Supabase advisor warnings about multiple permissive policies once the owner-based and account-based access model settles.
• Expand the Council workbench beyond starter-member cloning into full member editing, duplication, explicit knowledge-base link management, and marketplace acquisition/fork flows.

Phase 2: Knowledge and Trust

• Implement Supabase Auth, Postgres, Storage, and pgvector-backed document chunks.
• Add upload, chunking, embedding, and per-agent retrieval.
• Model bundled knowledge copies and licensed knowledge references so paid/protected marketplace artifacts can use retrieval without exposing raw source documents.
• Add citations, token/cost estimates, regeneration controls, and partial-failure states.
• Document model IDs, fallback behavior, data handling, and cost guardrails with each AI feature.

Phase 3: Sharing and Launch Shape

• Add public/unlisted council member templates, council templates, and shared conversations.
• Add "Duplicate to my account", permitted conversation forking, snapshot semantics, and member provenance.
• Add social sharing links for public templates and public council threads.
• Add generated Open Graph title, description, image, and canonical URL metadata for public council threads.
• Add marketplace artifact statuses, curated creator publishing, creator rights, and one-time paid acquisition for MVP paid artifacts.
• Add read-only shared council/conversation pages.
• Add export foundations for Markdown first, then PDF when the formatting target is clear.
• Use v0, AI Elements, and voice-oriented AI Elements patterns for UI exploration where they speed up screen design, then adapt reviewed output to this React Router app.

Verification Expectations

• Run npm run docs:living:check for documentation changes.
• Run npm run typecheck for app or route changes.
• Add focused tracer-bullet tests for AI route behavior, validation, streaming, and failure states as implementation begins.

Completed Phases

- Technology stack documented with the Vercel-first compute boundary, AI SDK, Vercel AI Gateway, AI Elements, voice-oriented AI Elements patterns, and v0 usage expectations. - Product requirements, market research, architecture, and implementation plan bootstrapped into specs/ as living-docs sources. - Council domain, marketplace artifact, snapshot, public thread, and social preview schema added as a Supabase migration with deterministic seed content. - Public homepage, marketplace list/detail pages, public council thread page, deterministic Open Graph SVG route, and /living-docs publisher route are implemented and cataloged in specs/development/routes.md. - Supabase Auth magic-link entry, /account workspace page, account membership schema, account-scoped council creation/configuration, model catalog/preferences, RAG document/chunk schema, query-run persistence schema, RAG snippet loading for council prompts, and reusable /resources/council-workbench fullstack component route are implemented locally with deterministic fallback when Supabase or AI Gateway are not configured. - The Supabase CLI is installed, .env targets project ref miridqqphvrbmnrzowdy, npm run supabase:project:check verifies the project name cosmic-council, and the current migrations have been pushed to the remote cosmic-council database. - Deterministic seed content has been applied to the remote cosmic-council database, and marketplace/public-thread loaders now read Supabase first with local seed fallback. - Account council creation now clones the starter Gods Cosmic Council member memberships, persists council/orchestrator model preference rows, supports orchestrator strategy/custom-instruction updates, and stores manual knowledge notes as RAG document/chunk rows. - Marketplace detail pages now embed /resources/marketplace-acquisition, which lets authenticated account editors duplicate free forkable council artifacts into private account councils while paid checkout and standalone member-library acquisition remain explicit missing work. - Public navigation now exposes sign-in/account entry points, and /auth/login is labeled as sign-in or registration for the Supabase magic-link flow. - The homepage has been upgraded from a demo-first page into a full SaaS landing page with account CTA, persona positioning, product mechanism, interactive council preview, feature matrix, marketplace/provenance section, launch packages, FAQ, and final conversion CTA. - Domain-readable public URLs now exist for the flagship beta council and marketplace artifact: /councils/featured/gods-cosmic-council-council-gods and /marketplace/featured/gods-cosmic-council-council-gods. The canonical public thread URL nests under its source council at /councils/featured/gods-cosmic-council-council-gods/threads/eternal-question-thread-eternal-question. The Gods Cosmic Council artifact is free during beta launch testing, publicly usable without login, and still duplicable into authenticated account workspaces.