dsiddharth2 · Apr 17, 2026 · Apr 16, 2026 · Apr 16, 2026 · Apr 16, 2026 · Apr 16, 2026
diff --git a/README.md b/README.md
@@ -6,12 +6,24 @@
 
 **Plug** is a package manager for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). It allows you to share, discover, and install reusable skills, commands, and agents across your projects via a rich, interactive Terminal User Interface (TUI).
 
+## Why Plug?
+
+Managing Claude Code extensions (Skills, Commands, and Agents) manually can quickly become unmanageable. Plug solves several key problems:
+
+*   **Corporate & Private Ecosystems**: Easily set up internal "Vaults" (GitHub repositories) to share proprietary coding standards, security guardrails, and specialized agents within your organization.
+*   **Consolidated Management**: Instead of maintaining multiple harnesses or manually copying Markdown files across different projects, Plug provides a single tool to discover, install, and update everything.
+*   **PlugVault Ecosystem**: Access a centralized, growing registry of community-contributed extensions through the official `plugvault`, or add your own custom vaults.
+*   **Zero-Bloat Workflow**: Keep your projects clean by installing only what you need, either locally to a project (`.claude/`) or globally (`~/.claude/`).
+
 ---
 
 ## 🚀 Quick Start: The Plug TUI
 
 The recommended way to use Plug is through its interactive TUI. It allows you to browse, search, and batch-install extensions without remembering complex commands.
 
+![Plug TUI Screenshot](docs/images/tui-screenshot.png)
+*(A rich, interactive interface for managing your Claude extensions)*
+
 ### 1. Install Plug
 Install as a Claude Code skill (recommended, no Node.js required):
 ```bash
@@ -44,6 +56,18 @@ Claude Code extensions (Skills, Commands, and Agents) are Markdown files. Plug s
 
 ---
 
+## 🔮 Vision & Roadmap: The Road to v1.0
+
+We are moving towards a decentralized, dependency-aware ecosystem. Our roadmap is divided into three key phases:
+
+*   **Phase A: Dependency Resolution**: Moving from single-package installs to full closure resolution using a DFS resolver.
+*   **Phase B: Community Marketplace**: Enabling any developer to publish from their own repo via automated frontmatter indexing.
+*   **Phase C: Claude Native Integration**: A zero-latency installer that works directly within Claude conversations.
+
+View the detailed [Ecosystem Vision & Roadmap](docs/project/ecosystem-vision.md).
+
+---
+
 ## Documentation
 
 *   **[TUI Guide](docs/features/tui.md)** — Detailed breakdown of the interactive interface and hotkeys.

diff --git a/docs/architecture.md b/docs/architecture.md
@@ -2,6 +2,15 @@
 
 Plug is a package manager for Claude Code extensions, designed to be lightweight, decentralized, and accessible through both a CLI and a native Claude Code Skill.
 
+## Why Plug? (The Value Proposition)
+
+In a corporate or team environment, maintaining consistency in Claude's behavior is critical. Plug addresses this by providing:
+
+1.  **Centralized Governance**: Define "Vaults" (registries) that house your organization's coding standards, security rules, and architectural guidelines.
+2.  **Private Ecosystems**: Support for private GitHub repositories allows companies to distribute proprietary skills and agents securely using standard GitHub authentication (PAT).
+3.  **Anti-Bloat Architecture**: One "harness" (Plug) manages all your extensions. You no longer need to manually sync Markdown files or maintain redundant harnesses across multiple projects.
+4.  **Community Knowledge**: The official `plugvault` provides a curated set of community best practices that can be shared and improved collectively.
+
 ## High-Level Design
 
 Plug operates on a "Vault" model. A Vault is any GitHub repository that follows a simple registry structure.
@@ -14,7 +23,12 @@ Plug operates on a "Vault" model. A Vault is any GitHub repository that follows
 
 ## Core Components
 
-### 1. Execution Engines
+### 1. Vault Ecosystem (PlugVault)
+A "Vault" is the unit of distribution. While the official `plugvault` repository serves as the primary community registry, Plug is designed to be multi-vault. Users can register any number of public or private vaults.
+*   **Resolution Order**: Plug searches vaults in a user-defined order, allowing internal corporate packages to override or supplement community versions.
+*   **Decentralization**: No central server is required; all package metadata and content live on GitHub.
+
+### 2. Execution Engines
 
 #### Claude Code Skill (Recommended)
 The Skill is the primary interface for most users. It runs directly within Claude Code, using Claude's native tools (`Bash`, `Read`, `Write`) to:
@@ -47,6 +61,49 @@ Plug supports three types of Claude Code extensions:
 2.  **Commands**: On-demand slash commands stored in `.claude/commands/`.
 3.  **Agents**: Specialized sub-agents for task delegation, stored in `.claude/agents/`.
 
+## Workflows
+
+Plug supports two primary workflows, bridging the gap between deep terminal discovery and zero-latency in-conversation management.
+
+### 1. TUI/CLI Workflow (The Discovery Engine) — **Current State**
+The TUI (powered by Node.js/Ink) is the rich, interactive "Browser" for the extension ecosystem.
+*   **Trigger**: User runs `plug` or `/plug` in a real terminal.
+*   **Fetch**: The client pulls `registry.json` from all configured vaults (official + corporate).
+*   **Search**: Real-time filtering by name, description, or tags.
+*   **Install**: Currently performs **single-package installation**. It downloads the requested package and its metadata directly to the project or global scope.
+*   **Capture**: Background tasks (like `git clone`) are captured via `AsyncLocalStorage` to keep the UI responsive.
+
+> **Note:** Dependency resolution is currently in development. At this stage, if a package requires other extensions, they must be installed manually.
+
+### 2. Claude Native Workflow (Zero-Latency Installer) — **Vision**
+The upcoming native integration allows managing extensions without leaving the Claude conversation, using a "smart installer" approach.
+*   **Trigger**: User types `/plug` inside Claude Code.
+*   **Zero-Latency**: Claude reads `~/.claude/commands/plug.md`—a pure instruction file that bypasses reasoning and immediately triggers `AskUserQuestion`.
+*   **Search (Natural Language)**: Claude fetches the `community-index.json`, performs semantic matching against user intent (e.g., "I need a security tool"), and presents matches.
+*   **Native Tools**: Installation is performed directly using Claude's native `Bash` (via `curl`), `Read`, and `Write` tools. No Node.js runtime is invoked during this flow.
+*   **Outcome**: Extensions are written directly to `.claude/` and are immediately available for use in the next turn.
+
+## The Unified Harness: Solving "Multi-Repo Bloat"
+
+Before Plug, using extensions from different sources required multiple specialized harnesses, leading to fragmented configurations and "tool bloat" within projects.
+
+Plug acts as the **unified harness**:
+*   **Single Source of Truth**: All extensions, regardless of their origin (official registry, company internal repo, or personal vault), are managed via one consistent interface.
+*   **Unified Pathing**: Extensions are routed to standard Claude Code directories (`.claude/skills/`, etc.) based on their type, ensuring Claude can always find them.
+*   **Global vs. Project Scoping**: Plug manages the complexity of global (`~/.claude/`) vs. project-specific (`.claude/`) installation, preventing duplicate configurations and ensuring a clean development environment.
+
+## Current vs. Future Capabilities (Sprints 1-3+)
+
+| Feature | Today (Built — Sprints 1 & 2) | Target (Vision — Sprint 3+) |
+|---|---|---|
+| **Installation** | Single-package | Full Dependency Resolution (DFS) |
+| **Marketplace** | Official Registry (`registry.json`) | Decentralized Community Index |
+| **Publishing** | Manual Metadata (`meta.json`) | Auto-indexing via Frontmatter |
+| **Search** | TUI Text Search | AI-powered Natural Language |
+| **Governance** | Manual Vault Registration | Auto-discovery of Community Vaults |
+
+See the full [Ecosystem Vision](project/ecosystem-vision.md) for a detailed roadmap of these phases.
+
 ## Security
 
 *   **Authentication**: Supports GitHub Personal Access Tokens (PAT) for private vaults. Tokens are stored in the global config or provided via environment variables (`PLUGVAULT_GITHUB_TOKEN`).

diff --git a/docs/features/tui.md b/docs/features/tui.md
@@ -4,33 +4,125 @@ Plug features a rich, interactive Terminal User Interface (TUI) built with **Ink
 
 ## Core Features
 
+![Plug TUI Screenshot](../images/tui-screenshot.png)
+*(The interactive TUI for Discover, Installed, and Vaults management)*
+
 *   **Interactive Browsing**: Explore available packages from all your registered vaults.
 *   **Search**: Find packages by name, description, or tags with real-time results.
 *   **Batch Operations**: Select multiple packages for installation or removal.
 *   **Vault Management**: Add, remove, and configure vaults (including private vault tokens) directly in the UI.
 *   **Contextual Feedback**: See detailed installation progress and result summaries.
 
+## Screens & Workflows
+
+The Plug TUI is designed to be the primary interface for all operations. No commands to memorize—just run `plug`.
+
+### Flow 1: Discover and Search
+The entry point for finding new extensions. Results from all registered vaults are merged into one list.
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│  plug  [Discover]  Installed  Vaults                           v2.0  │
+├──────────────────────────────────────────────────────────────────────┤
+│  / search...                                                          │
+├──────────────────────────────────────────────────────────────────────┤
+│                                                                       │
+│  NAME               TYPE     VER     DEPS        VAULT               │
+│  ▶ superpowers      skill    v1.0.0  ★ 3 deps    my-skills-repo 🔒  │
+│    senior-engineer  agent    v1.0.3  · no deps   official            │
+│    code-review      skill    v1.1.0  · no deps   official            │
+│    onboarding-kit   skill    v2.0.0  ★ 4 deps    company 🔒         │
+│                                                                       │
+│  🔒 = private vault    ✓ = already installed                         │
+│                                                                       │
+├──────────────────────────────────────────────────────────────────────┤
+│  [Enter] detail   [i] install   [/] search   [Tab] next tab          │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+*   **Real-time Filtering**: Press `/` to search. The list filters instantly as you type.
+*   **Private Badges**: Packages from private vaults are marked with a `🔒` badge.
+
 ---
 
-## Screens
-
-### 1. Discover
-The entry point for finding new extensions.
-*   **Tabs**: Filter by package type (Skills, Commands, Agents).
-*   **Search Bar**: Activate with `/` to filter the package list.
-*   **Install Queue**: Toggle packages with `Space` and install them all at once with `Enter`.
-
-### 2. My Packages
-Manage your currently installed extensions.
-*   **Scope View**: See both local and global installations.
-*   **Update Checks**: Check for newer versions and update them individually or in batch.
-*   **Safe Removal**: Uninstall packages and clean up their tracking data.
-
-### 3. Vaults
-Configure your package sources.
-*   **Resolve Order**: Change which vaults are prioritized during installation.
-*   **Private Vaults**: Interactively enter and update GitHub Personal Access Tokens (PAT).
-*   **Connectivity Test**: Instantly verify if a vault is reachable.
+### Flow 2: Package Detail & Dependency Awareness
+Press `Enter` on any package to see its full metadata, source vault, and dependency status.
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│  superpowers                                  [skill]  v1.0.0        │
+│  Gives Claude superpowers                                             │
+│                                                                       │
+│  Source: my-skills-repo (github.com/developer/my-skills-repo)        │
+│                                                                       │
+│  Dependencies:                                                        │
+│    ✓ senior-engineer   agent    v1.0.3   official           installed │
+│    ✗ code-review       skill    v1.1.0   official       not installed │
+│                                                                       │
+│  Installing this will also install: code-review (from official)      │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+### Flow 3: Install Plan & Scope Selection
+Press `i` to trigger the installation. Plug builds a "Plan" showing exactly what will be written.
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│  Install plan — superpowers                                          │
+├──────────────────────────────────────────────────────────────────────┤
+│  Install scope:  ◉ Project (.claude/)   ○ Global (~/.claude/)       │
+│                                                                       │
+│  Required — always installed:                                         │
+│    [✓] superpowers       skill    v1.0.0   new        my-skills-repo │
+│    [✓] code-review       skill    v1.1.0   new        official       │
+│                                                                       │
+│  Already satisfied — skipped:                                         │
+│    [✓] senior-engineer   agent    v1.0.3   installed  official       │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+*   **Scope Toggle**: Use `Tab` to switch between Project (`.claude/`) and Global (`~/.claude/`) installation.
+*   **Dependency Closure**: Plug automatically includes all required dependencies in the plan.
+
+---
+
+### Flow 4: My Packages (Installed)
+Manage your extensions across different scopes.
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│  plug  Discover  [Installed]  Vaults                                 │
+├──────────────────────────────────────────────────────────────────────┤
+│  SCOPE  NAME              TYPE     VER     VAULT                     │
+│  [G]    senior-engineer   agent    v1.0.3  official                  │
+│  [P]  ▶ superpowers       skill    v1.0.0  my-skills-repo            │
+│                                                                       │
+│  [G] global ~/.claude/   [P] project .claude/                        │
+├──────────────────────────────────────────────────────────────────────┤
+│  [Enter] detail   [d] uninstall   [u] update                         │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+*   **Uninstall Safety**: If you try to remove a package that others depend on, Plug will prompt you to either cascade the removal or force-remove just the target.
+
+---
+
+### Flow 5: Vault Management
+Add sources and manage authentication without touching a config file.
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│  Add vault                                                           │
+├──────────────────────────────────────────────────────────────────────┤
+│  Name: company                                                        │
+│  URL:  https://github.com/myco/claude-skills                         │
+│  Token: ••••••••••••••••  (for private repos)                        │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+*   **Community Discovery**: Browse a curated list of community vaults and add them with a single click.
 
 ---
 

diff --git a/docs/images/tui-screenshot.png b/docs/images/tui-screenshot.png