@cstack-protocol/pingala 1.0.0

package/HOSTED_SETUP.md

@@ -0,0 +1,54 @@
+# Pingala Cloud Governance — Inner Circle Onboarding
+
+Welcome to the **Pingala Cloud Governance** private beta. You are one of the first to test the hosted **Conscious Stack Index (CSI)** and **Stack Drift** governance layer.
+
+---
+
+## 1. Connection Details
+
+To connect your agent (Claude Desktop, etc.) to the gated Pingala server, use the following details:
+
+*   **Transport Type:** SSE (Server-Sent Events)
+*   **URL:** `https://pingala.consciousstack.com/sse` (or the provided preview URL)
+*   **Authorization:** `Bearer <YOUR_PRIVATE_TOKEN>`
+
+---
+
+## 2. Setup: Claude Desktop
+
+1. Open your `claude_desktop_config.json` (usually in `~/Library/Application Support/Claude/` on macOS).
+2. Add the following to your `mcpServers` object:
+
+```json
+{
+  "mcpServers": {
+    "pingala-cloud": {
+      "url": "https://pingala.consciousstack.com/sse",
+      "headers": {
+        "Authorization": "Bearer YOUR_PRIVATE_TOKEN_HERE"
+      }
+    }
+  }
+}
+```
+
+3. Restart Claude Desktop.
+
+---
+
+## 3. First Conversation
+
+Once connected, try asking Pingala:
+
+*   *"What is my current Stack Drift score?"*
+*   *"Audit my current workspace based on the 5:3:1 rule."*
+*   *"What is my Conscious Stack Index (CSI) status?"*
+
+---
+
+## 4. Feedback
+
+Please record your impressions, bugs, and "aha moments" in the shared group or via the `FEEDBACK.md` template.
+
+> [!IMPORTANT]
+> This is a high-sovereignty environment. Your tool names are never captured; only categories and structural metadata are processed to provide governance.

package/LANDING_PAGE_DESIGN.md

@@ -0,0 +1,46 @@
+# Pingala Cloud: Landing Page Design (`mcp.consciousstack.com`)
+
+## Visual Direction
+- **Aesthetic:** Dark mode, glassmorphism, iridescent gradients (Silicon/Quartz theme).
+- **Typography:** Inter or Outfit (Clean, Tech-Forward).
+- **Hero:** A pulsating geometric lattice (The Silica Unit Cell) that reacts to hover.
+
+---
+
+## Content Structure
+
+### 1. Hero Section
+**Headline:** Bridge the Cognitive Gap.  
+**Subhead:** The first Governance Layer for the Post-Clock Era. Hosted. Gated. Sovereign.  
+**Call to Action:** [Enter Access Token] (Primary Input) | [View Documentation] (Secondary Link)
+
+### 2. The Core Metric (Stack Drift)
+**Headline:** From Fragmentation to Resonance.  
+**Copy:** Stop tool bloat before it starts. Pingala monitors your workspace in real-time, computing your **Conscious Stack Index (CSI)** and **Stack Drift Score**.
+**Visual:** A progress bar or "Speedometer" showing the shift from "Fragmented" to "Aligned."
+
+### 3. The 5:3:1 Protocol
+**Headline:** Architectural Guardrails for AI Autonomy.  
+**Copy:** Pingala enforces the 5:3:1 Rule:
+- **1 Anchor Node:** Your center of truth.
+- **3 Active Nodes:** Your current focus.
+- **5 Supporting Nodes:** Your utility layer.
+**Visual:** A 3D representation of the 9-node boundary.
+
+### 4. Inner Circle Setup (The Quick Start)
+**Headline:** Connect in 60 Seconds.  
+**Copy:**
+1. Copy the connection URL: `pingala.consciousstack.com/sse`
+2. Open Claude Desktop Config.
+3. Paste your token.
+4. Pingala is now Governing your sessions.
+
+### 5. Manifesto Footer
+**Copy:** "Technology should amplify human value, not replace it. Pingala is your representative in the machine."
+
+---
+
+## Technical Setup (Vercel)
+- **Domain:** `mcp.consciousstack.com`
+- **Redirects:** `/` (this landing page) | `/sse` (MCP transport)
+- **Framework:** Next.js (recommended for the vibrant UI and serverless MCP integration).

package/MANUAL_VERCEL_STEPS.md

@@ -0,0 +1,39 @@
+# Manual Vercel Deployment Guide
+
+To finalize the launch of **Pingala Cloud Governance**, please follow these manual steps in your Vercel Dashboard.
+
+## 1. Create the Project
+1. Go to your [Vercel Dashboard](https://vercel.com/dashboard).
+2. Click **"Add New..." > "Project"**.
+3. Import the `cs-mcp-core` repository.
+   - *Note: The `@cstack/sdk` is now bundled internally, so relative path errors are resolved.*
+
+## 2. Configure Build Settings
+- **Framework Preset:** `Other` (or `Node.js`)
+- **Build Command:** `npm run build`
+- **Output Directory:** `build` (Wait, since we use `@vercel/node`, it'll look for matching source, but keeping `build` as the target for our transpiled JS is safer).
+- **Install Command:** `npm install`
+
+## 3. Environment Variables (Critical)
+Add the following variables in **Settings > Environment Variables**:
+
+| Variable | Value |
+| :--- | :--- |
+| `VALID_TOKENS` | `a10d64bb88876ddacd80ff4c3fd19f32,a67fb80f1b6bb508cd1149e1dd1c8033,d30c3ef8bb25ced0ddb3c2d954e21f46` |
+| `CSTACK_DATA_DIR` | `/tmp` |
+| `CSTACK_API_KEY` | *Your secret API key for the live registry (if applicable)* |
+
+## 4. Domain Setup
+1. Go to **Settings > Domains**.
+2. Add `mcp.consciousstack.com`.
+3. Follow the DNS instructions provided by Vercel (CNAME record).
+
+## 5. Deploy
+Click **Deploy**. Once finished, visiting `mcp.consciousstack.com` should show the new landing page, and the SSE transport will be live at `/sse`.
+
+---
+
+### Inner Circle Tokens (Reminder)
+- Tester 1: `a10d64bb88876ddacd80ff4c3fd19f32`
+- Tester 2: `a67fb80f1b6bb508cd1149e1dd1c8033`
+- Tester 3: `d30c3ef8bb25ced0ddb3c2d954e21f46`

package/PRODUCT-ROADMAP.md

@@ -0,0 +1,241 @@
+# CSTACK MCP Product Roadmap
+
+> **North Star**: Transform from an "Auditor" into a "Governor"—an interception layer that validates AI suggestions *before* action, not just reviews *after* the fact.
+
+---
+
+## Vision Architecture (from Notion AI Spec)
+
+The target architecture defines CSTACK MCP as a **governance-first** Model Context Protocol server with:
+
+| Capability | Description | Horizon |
+|------------|-------------|---------|
+| **Governance Tools** | `validate_stack_change`, `get_governance_context`, `calculate_csi` | H1-H2 |
+| **Specialized Agents** | `surgeon_audit`, `mirror_analysis` | H2-H3 |
+| **Resources** | `cstack://stack-map`, `cstack://csi/latest`, `cstack://maturity/status` | H1-H2 |
+| **Prompts** | `inject_constraints`, `canonical_output`, `augmentation_only` | H1 |
+| **Sincerity Filter** | Output compression and productivity-theater removal | H3 |
+| **Geometry Analysis** | Hexagonal vs. Cubic pattern detection | H3 |
+
+---
+
+## Horizon 1: Foundation (Now)
+
+**Constraints**: No external telemetry. Manual/self-reported inputs. Claude Desktop only.
+
+### Tools
+
+| Tool | Status | Notes |
+|------|--------|-------|
+| `cs_audit` | ✅ Complete | 6-step Intervention Logic, 5:3:1 validation |
+| `validate_stack_change` | 🔲 New | Gating tool—call *before* suggesting additions. Extracted from cs_audit logic. |
+| `get_governance_context` | 🔲 New | Exposes current stack state, maturity level, allowed/blocked actions |
+
+### Resources
+
+| Resource | Status | Notes |
+|----------|--------|-------|
+| `cstack://stack-map/current` | 🔲 New | JSON representation of 5:3:1 hierarchy |
+| `cstack://maturity/status` | 🔲 New | Level (1-5), stability days, gate requirements |
+
+### Prompts
+
+| Prompt | Status | Notes |
+|--------|--------|-------|
+| `inject_constraints` | 🔲 New | Wraps user requests with governance context |
+| `canonical_output` | 🔲 New | Forces Pingala structure: Target→Current→Recs→Guardrails→Workflow→Geometry→Notes |
+
+### Core Logic
+
+| Rule | Status | Notes |
+|------|--------|-------|
+| 5:3:1 Enforcement | ✅ Complete | Hard limits on Anchor/Active/Supporting |
+| Maturity Gates | 🔲 New | Block actions based on level + stability days |
+| Substitution Requirement | ✅ Complete | No addition without subtraction at capacity |
+
+### CSI Lite
+
+For H1, implement a **proxy-based CSI** without active testing:
+
+```
+CSI-Lite = (0.35 × AD) + (0.35 × DE) + (0.30 × DP-proxy)
+
+Where:
+- AD = Attention Depth (from Screen Time screenshot or self-report)
+- DE = Dependency Exposure (self-assessed workflow audit)
+- DP-proxy = Decisions with justification in cs_audit / total cs_audit calls
+```
+
+**Deferred**: Recall Fitness, Augmentation Integrity (require instrumentation).
+
+---
+
+### Horizon 1.5: Functional Scaling (Bāguà Alignment) - IN PROGRESS
+- **Functional Node Clustering**: Transition from counting "Binary Apps" to "Functional Slots."
+- **Contextual Adapters**: Map tools that serve the same purpose across different contexts (Mobile vs. Desktop) as one functional node.
+- **Bridge Coefficients**: Logic to identify "adapter" tools that bridge contexts without increasing cognitive sprawl.
+- **Role Drift Detection**: Identify "Ghost Active" tools where usage (telemetry) contradicts the assigned role (e.g., a "Supporting" tool consuming "Active" levels of time).
+
+---
+
+## Horizon 2: Telemetry Integration
+
+**Unlocked by**: FocusMonitor/CSTACK native integration, decision journal, vault parsing.
+
+### Tools
+
+| Tool | Status | Notes |
+|------|--------|-------|
+| `calculate_csi` | 🔲 Planned | Full 5-pillar calculation with telemetry |
+| `surgeon_audit` | 🔲 Planned | Subtraction recommendations based on usage data |
+| `mirror_analysis` | 🔲 Planned | Claimed vs. actual usage alignment |
+| `record_intervention` | 🔲 Planned | Billing ledger for governance actions |
+
+### Resources
+
+| Resource | Status | Notes |
+|----------|--------|-------|
+| `cstack://csi/latest` | 🔲 Planned | Full CSI breakdown with trend |
+| `cstack://telemetry/usage` | 🔲 Planned | Tool usage time-series from FocusMonitor |
+| `cstack://billing/ledger` | 🔲 Planned | Monthly intervention log with value delivered |
+
+### CSI Full Formula
+
+```python
+WEIGHTS = {
+    "decision_provenance": 0.30,
+    "augmentation_integrity": 0.25,
+    "attention_depth": 0.20,
+    "dependency_exposure": 0.15,
+    "recall_fitness": 0.10
+}
+
+CSI = (0.30 × DP) + (0.25 × AI) + (0.20 × AD) + (0.15 × DE) + (0.10 × RF)
+```
+
+**Component Data Sources**:
+
+| Component | Data Source | H2 Status |
+|-----------|-------------|-----------|
+| Decision Provenance | Decision journal + cs_audit justifications | 🔲 Requires journal |
+| Augmentation Integrity | Edit-before-accept rate (conversation analysis) | 🔲 Requires Claude log access |
+| Attention Depth | FocusMonitor deep_work_hours | ✅ Available via FocusMonitor |
+| Dependency Exposure | Workflow completion without AI (self-report + inference) | ⚠️ Partial |
+| Recall Fitness | Deferred to H3 | ❌ Requires active testing |
+
+---
+
+## Horizon 3: Advanced Governance
+
+**Unlocked by**: Full telemetry pipeline, graph-based analysis, enterprise features.
+
+### Tools
+
+| Tool | Status | Notes |
+|------|--------|-------|
+| `audit_stack_geometry` | 🔲 Future | Hexagonal vs. Cubic pattern detection |
+
+### Core Logic
+
+| Rule | Status | Notes |
+|------|--------|-------|
+| Lattice Geometry Detection | 🔲 Future | Requires tool-to-tool transition graph |
+| Sincerity Filter | 🔲 Future | Output compression based on CSI + transparency options |
+
+### Geometry Detection Algorithm
+
+```python
+def analyze_lattice_geometry(usage_graph, anchor_node):
+    """
+    Classifies stack as:
+    - hexagonal_dominant: Healthy exploration with anchor closure
+    - cubic_risk: Rigid automation, anchor marginalized
+    - quartz: 3D network with strong anchor coordination
+    - transitional: Mixed patterns, needs observation
+    """
+    hex_cycles = count_6_cycles_through_anchor(usage_graph, anchor_node)
+    cubic_paths = count_automation_chains_without_review(usage_graph)
+    anchor_centrality = betweenness_centrality(usage_graph, anchor_node)
+    
+    # Classification logic...
+```
+
+**Data Requirement**: Sequential tool invocation logs with timestamps. Not available in Claude Desktop alone.
+
+### Recall Fitness (Deferred)
+
+Options for H3:
+1. **Spaced-repetition prompts** built into CSTACK app
+2. **Weekly micro-quiz** delivered via notification
+3. **Proxy via search frequency** (more lookups = lower RF)
+
+---
+
+## Horizon 4: Institutional & Marketplace
+
+| Feature | Notes |
+|---------|-------|
+| Team-wide CSI aggregation | Org-level sovereignty dashboards |
+| Policy-aware orchestration | Enterprise approved-tool lists |
+| Congestion Alerts | Slack/Notion integrations for erosion warnings |
+| Notion Agent Marketplace | Package for public distribution |
+
+---
+
+## Implementation Principles
+
+### 1. Defense in Depth (Addressing Prompt Injection)
+
+LLMs are probabilistic. Governance rules can be "forgotten" or bypassed. Mitigations:
+
+- **Redundancy**: Inject rules in system prompt, tool descriptions, *and* required first-call.
+- **Structural Enforcement**: Tools return hard `allowed: false` regardless of LLM obedience.
+- **Audit Trail**: Log bypass attempts when tools are called without validation.
+- **Model Tuning**: Document that this MCP is optimized for Claude; other models may drift.
+
+### 2. Transparency Over Paternalism (Sincerity Filter)
+
+When filtering/compressing output:
+- Always show reasoning: "Condensed because CSI is 62."
+- Offer tiers: Full / Condensed / Bullet-only.
+- Allow opt-out: `sincerity_filter: off` setting.
+
+### 3. Proxy First, Instrument Later
+
+For metrics without direct data sources:
+- Start with self-report or inferred proxies.
+- Replace with instrumented data when available.
+- Never show a metric you can't defend.
+
+---
+
+## Current Status
+
+| Phase | Status | Target |
+|-------|--------|--------|
+| Horizon 1 | 🔄 In Progress | Q1 2026 |
+| Horizon 2 | 🔲 Planned | Q2-Q3 2026 |
+| Horizon 3 | 🔲 Future | Q4 2026+ |
+| Horizon 4 | 🔲 Vision | 2027+ |
+
+---
+
+## References
+
+- **Notion AI Spec**: Full governance layer specification (internal)
+- **CSI Formula**: 5-pillar weighted calculation (see above)
+- **5:3:1 Protocol**: 1 Anchor + 3 Active + 5 Supporting = 9 max
+- **Pingala Engine**: Core governance logic in `src/core/pingala.ts`
+- **Methodology Loader**: Dynamic rule ingestion from `cs-agent-core`
+
+---
+
+## Release Tech Debt (Inner Circle)
+
+- **Bundled SDK**: For the Monday Feb 9 release, `@cstack/sdk` has been manually bundled into `pingala-mcp/sdk` to ensure Vercel deployment stability (avoiding cross-repo relative path issues). 
+  - **Resolution Path**: After public release, migrate to a private NPM registry (@cstack/sdk) to restore a single source of truth.
+  - **Status**: TEMPORARY (Accepted for speed).
+
+---
+
+*Last updated: 2026-02-04*

package/PROVISIONING_GUIDE.md

@@ -0,0 +1,39 @@
+# Procedure: Provisioning Inner Circle Access
+
+Follow these steps to generate a new token and grant a tester access to the Pingala Cloud Governance server.
+
+## 1. Generate the Token
+Run the generation script from the root of the `pingala-mcp` repository:
+
+```bash
+node scripts/generate-token.js
+```
+
+**Output Example:**
+`7df658500907f854ce76eaf00e995b6a`
+
+## 2. Provision on Vercel
+Access to the hosted server is controlled by the `VALID_TOKENS` environment variable.
+
+1.  Log in to your **Vercel Dashboard**.
+2.  Select the **Pingala MCP** project.
+3.  Go to **Settings > Environment Variables**.
+4.  Find the `VALID_TOKENS` variable.
+5.  Edit the value and append the new token using a comma as a separator.
+    *   *Example:* `token1,token2,7df658500907f854ce76eaf00e995b6a`
+6.  **Save** the variable.
+7.  *(Optional but recommended)* Trigger a redeploy of the latest production deployment to ensure the changes are hot-loaded, although Node.js usually picks these up on the next request in many serverless environments.
+
+## 3. Issue to Tester
+Send the tester the following:
+
+1.  Their **Private Token**.
+2.  The **Connection URL**: `https://pingala.consciousstack.com/sse`
+3.  The [HOSTED_SETUP.md](file:///Users/georgesiosi/Documents/GitHub/conscious-stack/_active/pingala-mcp/HOSTED_SETUP.md) guide.
+
+---
+
+## Token Governance Rules
+- **Limit:** Max 5 active tokens for the Inner Circle.
+- **Revocation:** To revoke access, simply remove the token from the `VALID_TOKENS` list on Vercel.
+- **Privacy:** Tokens represent architectural sessions; no personal data is linked to the token itself.

package/README.md

@@ -0,0 +1,38 @@
+# Pingala MCP (The Reference Governor)
+
+The official governance layer for the Conscious Stack™ ecosystem. This MCP server enforces the 5:3:1 protocol and provides diagnostic tools for "Reflective Operators" to maintain cognitive sovereignty.
+
+## Features
+- **5:3:1 Enforcement**: Automated auditing of tool counts and roles.
+- **Cognitive Sovereignty Index (CSI)**: Quantitative assessment based on foundational work by Robert Duran IV.
+- **Stack Alignment Score (SAS)**: Comparative analysis of stack configurations.
+- **Powered by Pingala**: Highly opinionated governance engine with a strategic auditor voice.
+
+## Installation
+
+```bash
+cd pingala-mcp
+npm install
+npm run build
+```
+
+## Integration with Claude Desktop
+
+Add this to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "pingala": {
+      "command": "node",
+      "args": ["/Users/georgesiosi/Documents/GitHub/conscious-stack/_active/pingala-mcp/build/index.js"]
+    }
+  }
+}
+```
+
+## Tools
+- `audit_workspace`: Scans a directory for `.agent` configuration and evaluates alignment.
+
+---
+© 2026 Faiabrand Pte Ltd. High Sovereignty by Design.

package/ROADMAP.md

@@ -0,0 +1,21 @@
+# CSTACK MCP Roadmap
+
+> **📍 See [PRODUCT-ROADMAP.md](./PRODUCT-ROADMAP.md) for the comprehensive, horizon-based roadmap.**
+
+This document is retained for historical reference only.
+
+---
+
+## Legacy Milestones
+
+### MVP (Complete - Jan 2026)
+- [x] Repository scaffolding (TypeScript + MCP SDK)
+- [x] Initial `audit_workspace` tool → evolved to `cs_audit`
+- [x] Core 5:3:1 validation logic
+- [x] CSI/SAS metric foundations
+- [x] 6-step Intervention Logic
+- [x] Methodology ingestion from `cs-agent-core`
+
+---
+
+*For current roadmap, horizons, and implementation details, see **[PRODUCT-ROADMAP.md](./PRODUCT-ROADMAP.md)**.*