docs: add enterprise badges and VitePress documentation site

.github/workflows/deploy-docs.yml

@@ -0,0 +1,50 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - name: Install dependencies
+        run: npm ci
+      - name: Build docs
+        run: npm run docs:build
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/.vitepress/dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    name: Deploy
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -14,3 +14,7 @@ AGENTS.md
 
 # Personal, machine-local context
 .scope/memory/user.md
+
+# VitePress
+docs/.vitepress/dist
+docs/.vitepress/cache

docs/.vitepress/config.ts

@@ -0,0 +1,36 @@
+import { defineConfig } from 'vitepress'
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: "agenticscope",
+  description: "A directory-as-context standard plus a read-only MCP server",
+  base: "/agentic-scope/", // Required for GitHub Pages if repo name is agentic-scope
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'Guide', link: '/guide/' }
+    ],
+
+    sidebar: [
+      {
+        text: 'Introduction',
+        items: [
+          { text: 'What is agenticscope?', link: '/guide/' },
+          { text: 'Getting Started', link: '/guide/getting-started' }
+        ]
+      },
+      {
+        text: 'Core Concepts',
+        items: [
+          { text: 'Configuration', link: '/guide/configuration' },
+          { text: 'MCP Server', link: '/guide/mcp-server' }
+        ]
+      }
+    ],
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/jessn-dev/agentic-scope' }
+    ]
+  }
+})

docs/guide/configuration.md

@@ -0,0 +1,44 @@
+# Configuration & Manifest
+
+The `agenticscope.toml` file is the heart of your project's context. It acts as an index, dictating exactly which fragments load under specific conditions.
+
+## The Scope Definition
+
+At the top of the manifest, the `[scope]` block defines global constraints.
+
+```toml
+[scope]
+version    = "0.1.0"
+name       = "my-project"
+budget     = 4000     # Hard cap (estimated tokens) per context pack
+precedence = "type"   # Ordering strategy: "type" or "priority"
+```
+
+## Fragment Types
+
+Every fragment within `.scope/` must be assigned a type. Types carry intrinsic semantic precedence:
+
+1. **`rule`:** Behavioral guidance and absolute directives (Highest priority).
+2. **`spec`:** Active, current task requirements.
+3. **`persona`:** Swappable behavioral hats for the agent.
+4. **`memory`:** Historical architectural decisions, project logs, and state.
+5. **`knowledge`:** Static reference data (Lowest priority, loaded lazily).
+
+## Defining Fragments
+
+Fragments are defined in the manifest using `[[fragment]]` blocks. They are matched against tasks using two distinct mechanisms:
+
+- **`triggers`:** Glob patterns matched strictly against concrete file paths.
+- **`keywords`:** Plain text matched (case-insensitive substring) against the natural language task description.
+
+```toml
+[[fragment]]
+id       = "db-schema"
+type     = "knowledge"
+path     = ".scope/knowledge/schema.sql"
+triggers = ["**/*.sql", "db/**"]                 # Activates if an SQL file is touched
+keywords = ["migration", "schema", "database"] # Activates if these words are mentioned
+priority = 20
+```
+
+Keeping triggers and keywords deliberately separate prevents aggressive glob patterns (like `**/*.ts`) from falsely matching against unrelated task text.

docs/guide/getting-started.md

@@ -0,0 +1,55 @@
+# Getting Started
+
+This guide will walk you through installing agenticscope, scaffolding your first workspace, and packing context for an AI agent.
+
+## Prerequisites
+
+- **Node.js:** Ensure you have Node.js version 22 or higher installed.
+- **An AI Assistant:** A compatible agent (e.g., Claude Code, Cursor, Gemini, or a raw CLI model).
+
+## Installation
+
+We recommend installing the CLI globally so both `agenticscope` and the `agenticscope-mcp` server are available across all your repositories.
+
+```bash
+npm install -g agenticscope
+```
+
+*(Alternatively, you can run commands ad-hoc using `npx agenticscope <command>`)*
+
+## Initializing a Project
+
+Navigate to your project's root directory and run the initialization command. This scaffolds the `agenticscope.toml` manifest and a `.scope/` directory populated with placeholder fragments.
+
+```bash
+cd my-project
+agenticscope init
+```
+
+## Validating the Manifest
+
+After customizing your fragments, ensure your manifest is syntactically correct, trigger paths are valid, and no fragment violates the token budget.
+
+```bash
+agenticscope lint
+```
+
+## Packing Context
+
+The `pack` command resolves a specific task into a budgeted context block. It evaluates your task against the manifest triggers and keywords, printing only the context that matches.
+
+```bash
+agenticscope pack "fix the sql migration"
+```
+
+If you want exact token counts using the `cl100k_base` tokenizer, append the `--exact` flag.
+
+## Compiling Vendor Files
+
+To synchronize your `.scope/` tree into native configuration files (`CLAUDE.md`, `GEMINI.md`, `.cursorrules`, etc.), use the `build` command:
+
+```bash
+agenticscope build
+```
+
+For continuous integration pipelines, you can run `agenticscope build --check` to verify that generated files haven't drifted from their source.

docs/guide/index.md

@@ -0,0 +1,24 @@
+# Introduction to agenticscope
+
+**agenticscope** is a directory-as-context standard coupled with an integrated Model Context Protocol (MCP) server. It equips AI coding agents with deep, structured awareness of your workspace without needlessly exhausting your context window.
+
+## The Context Problem
+
+Currently, developers feed AI agents context via monolithic files (e.g., `.cursorrules`, `CLAUDE.md`, `GEMINI.md`, or `AGENTS.md`). As projects scale, these files bloat, combining immutable coding standards, database schemas, architectural decisions, and temporary task notes into a single, unwieldy document.
+
+This creates significant friction:
+- **Token Exhaustion:** The agent re-reads irrelevant data (like SQL schemas when modifying CSS) on every inference cycle.
+- **Priority Dilution:** Strict behavioral constraints ("never use `any`") are drowned out by sprawling reference materials.
+- **Vendor Fragmentation:** Disparate platforms require their own dedicated context files (e.g., `.claude/`, `.gemini/`), which inevitably drift out of sync.
+
+## The agenticscope Solution
+
+agenticscope resolves these challenges through a targeted, indexed approach:
+
+1. **Typed Fragments:** Context is modularized into distinct, typed fragments (`rules`, `knowledge`, `specs`, `personas`, `memory`).
+2. **Smart Triggers:** Fragments only load when their associated glob paths or keywords match the current task.
+3. **Strict Budgeting:** Context is constrained by a strict token budget, dropping lower-priority fragments gracefully.
+4. **Universal Compilation:** A single `.scope/` directory is compiled natively for multiple vendors instantly (outputting `.cursorrules`, `CLAUDE.md`, `GEMINI.md`, and `AGENTS.md`).
+5. **Live MCP Integration:** Advanced clients like **Windsurf**, **Zed**, and **Cursor** can bypass static files entirely. The accompanying MCP server exposes your environment dynamically, letting the agent query active plans, git state, and subagents on demand.
+
+Next, head over to [Getting Started](./getting-started.md) to install the CLI and scaffold your first project.

docs/guide/mcp-server.md

@@ -0,0 +1,51 @@
+# MCP Server
+
+agenticscope ships with a fully integrated, read-only Model Context Protocol (MCP) server. This server grants compatible AI assistants (like Claude Desktop, Cursor, and Windsurf) dynamic, real-time awareness of your workspace.
+
+## Available Tools
+
+The server exposes several tools that the AI can invoke autonomously:
+
+| Tool | Description |
+| :--- | :--- |
+| `list_projects` | Enumerates initialized agenticscope projects within the workspace. |
+| `list_subagents` | Retrieves available personas (`.scope/personas`) for a project. |
+| `list_plans` | Exposes active specs/plans in flight. |
+| `git_status` | Reports the repository state (branch, ahead/behind commits, dirty tree status). |
+| `grep_memory` | Executes a fast grep search across `.scope/memory/` decision records. |
+| `pack_context` | Resolves a task description into a token-budgeted context payload. |
+
+## Security & Constraints
+
+By design, the MCP server is completely **read-only**. 
+
+Furthermore, all `project` arguments are **scope-guarded** to the workspace root. The server enforces strict path validation to guarantee that directory traversal attacks (e.g., `../../secrets`) or absolute paths pointing outside the workspace are rejected instantly.
+
+## Connecting the Server
+
+To connect the server, configure your AI host to invoke `agenticscope-mcp`. For example, in Claude Desktop (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "agenticscope": {
+      "command": "npx",
+      "args": ["-y", "agenticscope", "agenticscope-mcp", "--workspace", "~/Documents/projects"]
+    }
+  }
+}
+```
+
+You can also use the CLI to generate host-specific, ready-to-paste configurations:
+
+```bash
+agenticscope mcp-config --host cursor --workspace ~/Documents/projects
+```
+
+## Remote Transport (HTTP)
+
+While the server operates over standard I/O (stdio) by default, you can expose it as a shared service over HTTP for remote or hosted environments:
+
+```bash
+agenticscope-mcp --http 3000 --workspace ~/Documents/projects
+```

docs/index.md

@@ -0,0 +1,35 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: "agenticscope"
+  text: "Directory-as-context for AI"
+  tagline: A unified standard and read-only MCP server that grants your AI agents structured, token-efficient awareness of your workspace.
+  actions:
+    - theme: brand
+      text: Read the Docs
+      link: /guide/
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/jessn-dev/agentic-scope
+
+features:
+  - title: Predictable Context
+    details: A lightweight manifest dictates exactly what context loads. Fragments are strictly typed and prioritized under a defined token budget.
+  - title: Live Workspace Awareness
+    details: The integrated, read-only MCP server gives any capable AI real-time, structured access to git status, open plans, and active subagents.
+  - title: Universal Vendor Support
+    details: Compile a single `.scope/` context tree into native, optimized constraint files (`.cursorrules`, `CLAUDE.md`, `GEMINI.md`, `AGENTS.md`) or bypass files entirely using the MCP server for advanced clients like Windsurf and Zed.
+---
+
+<div class="vp-doc">
+<br>
+
+## Why agenticscope?
+
+Modern AI coding assistants require profound context to be effective. However, dumping your entire architecture into monolithic files—whether it's `.cursorrules`, `CLAUDE.md`, `GEMINI.md`, or `AGENTS.md`—wastes tokens, introduces crippling noise, and causes the model to prioritize background reference data over strict behavioral rules.
+
+**agenticscope** reimagines project context by indexing it. Your AI queries a structured, budgeted manifest of rules, personas, and database schemas—reading only what is highly relevant to the immediate task. Advanced MCP-capable clients (like **Windsurf**, **Zed**, and **Claude Desktop**) don't even need to read static files at all; they dynamically query the `agenticscope-mcp` server exactly when they need to.
+
+</div>