feat: git-based pack registries

README.md

@@ -398,6 +398,33 @@ libscope pack create --name "react-docs" --topic react
 libscope pack install ./react-docs.json
 ```
 
+### Pack Registries
+
+Share and discover knowledge packs through git-based registries. A registry is a git repo with a defined folder structure managed by libscope.
+
+```bash
+# Add a registry
+libscope registry add https://github.com/org/libscope-registry.git --name official
+
+# Search for packs across all registries
+libscope registry search "react"
+
+# Install a pack by name (resolves from registries)
+libscope pack install react-docs
+libscope pack install react-docs@1.2.0    # specific version
+
+# Create your own registry
+libscope registry create ./my-registry
+
+# Publish a pack file to your registry
+libscope registry publish ./my-pack.json -r my-registry --version 1.0.0
+
+# Submit a pack to someone else's registry (creates a feature branch)
+libscope registry publish ./my-pack.json -r community --submit
+```
+
+Authentication is delegated to git — SSH keys and HTTPS credential helpers work automatically. Registries cache locally and support offline index lookups. See the [Pack Registries guide](/guide/pack-registries) for full details.
+
 There's also a web dashboard at `http://localhost:3377` when you run `libscope serve`, with search, document browsing, topic navigation, and a knowledge graph visualization at `/graph`.
 
 <details>
@@ -479,6 +506,19 @@ There's also a web dashboard at `http://localhost:3377` when you run `libscope s
 | `libscope add-repo <url>`          | Index a GitHub/GitLab repo |
 | `libscope disconnect <name>`       | Remove connector data      |
 
+**Registries**
+
+| Command                                               | Description                              |
+| ----------------------------------------------------- | ---------------------------------------- |
+| `libscope registry add <url> [-n <alias>]`            | Register a git repo as a pack registry   |
+| `libscope registry remove <name>`                     | Unregister a registry                    |
+| `libscope registry list`                              | List configured registries               |
+| `libscope registry sync [<name>]`                     | Sync one or all registries               |
+| `libscope registry search <query> [-r <name>]`        | Search registry pack indexes             |
+| `libscope registry create <path>`                     | Initialize a new registry repo           |
+| `libscope registry publish <file> -r <name>`          | Publish a pack file to a registry        |
+| `libscope registry unpublish <pack> -r <name>`        | Remove a pack version from a registry    |
+
 **Utilities**
 
 | Command                           | Description                  |

docs/.vitepress/config.ts

@@ -56,6 +56,7 @@ export default defineConfig({
             { text: "MCP Setup", link: "/guide/mcp-setup" },
             { text: "Connectors", link: "/guide/connectors" },
             { text: "Knowledge Packs", link: "/guide/knowledge-packs" },
+            { text: "Pack Registries", link: "/guide/pack-registries" },
             {
               text: "Programmatic Usage",
               link: "/guide/programmatic-usage",
@@ -77,6 +78,7 @@ export default defineConfig({
             { text: "CLI Commands", link: "/reference/cli" },
             { text: "MCP Tools", link: "/reference/mcp-tools" },
             { text: "REST API", link: "/reference/rest-api" },
+            { text: "Registry", link: "/reference/registry" },
             { text: "Configuration", link: "/reference/configuration" },
           ],
         },

docs/guide/pack-registries.md

@@ -0,0 +1,121 @@
+# Pack Registries
+
+Pack registries are git repositories with a well-defined folder structure that serve as shared catalogs of knowledge packs. You can add public or private registries, search them for packs, and install packs directly by name. If you maintain your own registry, you can publish packs to it — or submit packs to someone else's registry via a PR workflow.
+
+Authentication is handled entirely by git. If you have SSH keys or an HTTPS credential helper configured, private registries work automatically.
+
+## Adding a Registry
+
+```bash
+# Add a public registry
+libscope registry add https://github.com/org/libscope-registry.git
+
+# Add with a custom alias and priority
+libscope registry add git@github.com:team/internal-packs.git --name team-packs --priority 5
+
+# Add with auto-sync every 24 hours
+libscope registry add https://github.com/org/registry.git --sync-interval 86400
+
+# Add without cloning immediately
+libscope registry add https://github.com/org/registry.git --no-sync
+
+# List configured registries
+libscope registry list
+
+# Remove a registry
+libscope registry remove team-packs
+```
+
+On first add, libscope clones the registry's index locally to `~/.libscope/registries/<name>/`. Subsequent syncs fetch only changes.
+
+## Searching Registries
+
+```bash
+# Search all registries
+libscope registry search "react"
+
+# Search a specific registry
+libscope registry search "react" -r official
+```
+
+Results show the pack name, description, tags, latest version, and which registry it came from.
+
+## Installing Packs from a Registry
+
+The existing `pack install` command now resolves packs from your configured registries:
+
+```bash
+# Install the latest version
+libscope pack install react-docs
+
+# Install a specific version
+libscope pack install react-docs --version 1.2.0
+# or
+libscope pack install react-docs@1.2.0
+
+# Install from a specific registry (skips conflict resolution)
+libscope pack install react-docs --registry official
+```
+
+If multiple registries contain a pack with the same name, libscope resolves the conflict by priority (lower `priority` value wins). You can override this with `--registry <name>`.
+
+### Offline Behavior
+
+If a registry is unreachable during install, libscope falls back to the cached index with a warning. If the registry has never been synced, it tells you to run `libscope registry sync` when online.
+
+## Syncing Registries
+
+```bash
+# Sync all registries
+libscope registry sync
+
+# Sync a specific registry
+libscope registry sync official
+```
+
+Registries also auto-sync when the local cache is older than the configured `syncInterval` (in seconds). This happens automatically before pack installs when the cache is stale.
+
+## Creating Your Own Registry
+
+```bash
+# Initialize a new registry repo
+libscope registry create ./my-registry
+cd my-registry && git remote add origin <your-git-url> && git push -u origin main
+```
+
+This creates a git repo with the correct folder structure (`index.json`, `packs/` directory) and an initial commit. Push it to any git host to share it.
+
+## Publishing Packs
+
+```bash
+# Publish a pack file to a registry you own
+libscope registry publish ./my-pack.json -r my-registry --version 1.0.0
+
+# Auto-bump patch version (from latest in registry)
+libscope registry publish ./my-pack.json -r my-registry
+
+# Submit a pack to someone else's registry (creates a feature branch)
+libscope registry publish ./my-pack.json -r community --submit
+
+# Unpublish a specific version
+libscope registry unpublish my-pack -r my-registry --version 1.0.0
+```
+
+Publishing assembles the pack into the registry's folder structure, generates a SHA-256 checksum, updates `index.json` and `pack.json`, and commits + pushes. The `--submit` flag pushes to a `feature/add-<pack-name>` branch instead — you then create a pull request manually.
+
+### Checksum Validation
+
+Every published pack version includes a `checksum.sha256` file. On install, libscope verifies the checksum before extracting. A mismatch fails the install with a clear error.
+
+## Versioning
+
+Pack versions follow [semver](https://semver.org/) (e.g. `1.0.0`, `1.2.3`). When you publish without `--version`, the patch version is auto-bumped from the latest. Old versions are preserved in the registry. `pack install` defaults to the latest version unless you specify one.
+
+## MCP Usage
+
+Your AI assistant can also work with registries through MCP:
+
+- `install-pack` — install from a registry by name
+- `list-packs --available` — browse packs available in registries
+
+See the [Registry Reference](/reference/registry) for complete schema details, configuration format, and all CLI flags.

docs/reference/cli.md

@@ -240,11 +240,103 @@ libscope link <sourceId> <targetId> --type see_also --label "Background context"
 
 | Command                              | Description                                       |
 | ------------------------------------ | ------------------------------------------------- |
-| `libscope pack install <nameOrPath>` | Install a pack (from registry or file)            |
+| `libscope pack install <nameOrPath>` | Install a pack (from registry, file, or by name)  |
 | `libscope pack remove <name>`        | Remove a pack and its documents                   |
 | `libscope pack list`                 | List installed packs (`--available` for registry) |
 | `libscope pack create`               | Export documents as a pack file                   |
 
+### `libscope pack install` (registry support)
+
+When no local file path is given, `pack install` searches configured registries:
+
+```bash
+libscope pack install react-docs              # latest from any registry
+libscope pack install react-docs@1.2.0        # specific version
+libscope pack install react-docs --version 1.2.0
+libscope pack install react-docs --registry official
+```
+
+| Option               | Description                                  |
+| -------------------- | -------------------------------------------- |
+| `--version <semver>` | Install a specific version (default: latest) |
+| `--registry <name>`  | Install from a specific registry             |
+
+## Pack Registries
+
+| Command                                                    | Description                            |
+| ---------------------------------------------------------- | -------------------------------------- |
+| `libscope registry add <url> [-n <alias>]`                | Register a git repo as a pack registry |
+| `libscope registry remove <name> [-y]`                     | Unregister a registry                  |
+| `libscope registry list`                                   | List configured registries             |
+| `libscope registry sync [<name>]`                          | Sync one or all registries             |
+| `libscope registry search <query> [-r <name>]`             | Search registry pack indexes           |
+| `libscope registry create <path>`                          | Initialize a new registry repo         |
+| `libscope registry publish <file> -r <name>`               | Publish a pack file to a registry      |
+| `libscope registry unpublish <pack> -r <name> --version <v>` | Remove a pack version from a registry |
+
+### `libscope registry add`
+
+```bash
+libscope registry add https://github.com/org/registry.git
+libscope registry add git@github.com:team/packs.git --name team --priority 5
+libscope registry add https://github.com/org/registry.git --sync-interval 86400 --no-sync
+```
+
+| Option                       | Description                                              |
+| ---------------------------- | -------------------------------------------------------- |
+| `-n, --name <alias>`        | Short name for this registry (default: inferred from URL)|
+| `--priority <n>`            | Conflict resolution priority — lower wins (default: 10)  |
+| `--sync-interval <seconds>` | Auto-sync interval in seconds, 0 = manual (default: 0)   |
+| `--no-sync`                 | Skip initial sync after adding                            |
+
+### `libscope registry search`
+
+```bash
+libscope registry search "react"
+libscope registry search "kubernetes" -r official
+```
+
+### `libscope registry publish`
+
+```bash
+# Direct publish (you have write access)
+libscope registry publish ./my-pack.json -r my-registry --version 1.0.0
+
+# Auto-bump patch version
+libscope registry publish ./my-pack.json -r my-registry
+
+# Submit via feature branch (for PR workflow)
+libscope registry publish ./my-pack.json -r community --submit
+```
+
+| Option                   | Description                                              |
+| ------------------------ | -------------------------------------------------------- |
+| `-r, --registry <name>`  | Target registry (required)                              |
+| `--version <semver>`     | Version to publish as (default: auto-bump patch)         |
+| `-m, --message <msg>`    | Git commit message                                      |
+| `--submit`               | Push to a feature branch instead of main                 |
+
+### `libscope registry unpublish`
+
+```bash
+libscope registry unpublish my-pack -r my-registry --version 1.0.0
+```
+
+| Option                   | Description                       |
+| ------------------------ | --------------------------------- |
+| `-r, --registry <name>`  | Target registry (required)       |
+| `--version <semver>`     | Version to remove (required)      |
+| `-m, --message <msg>`    | Git commit message                |
+| `-y, --yes`              | Skip confirmation prompt          |
+
+### `libscope registry create`
+
+```bash
+libscope registry create ./my-registry
+```
+
+Creates a git repo with the canonical registry folder structure. See the [Registry Reference](/reference/registry) for full schema details.
+
 ## Connectors
 
 | Command                            | Description                      |