vcs-python · tony · Mar 24, 2026 · Mar 24, 2026 · Mar 24, 2026
diff --git a/docs/api/index.md b/docs/api/index.md
@@ -3,23 +3,56 @@
 # API Reference
 
 :::{seealso}
-For granular control see the [libvcs documentation](https://libvcs.git-pull.com/en/latest/)—especially the sections on [commands](https://libvcs.git-pull.com/en/latest/usage/commands.html) and [projects](https://libvcs.git-pull.com/en/latest/usage/projects.html).
+For granular control see the [libvcs documentation](https://libvcs.git-pull.com/en/latest/)---especially the sections on [commands](https://libvcs.git-pull.com/en/latest/usage/commands.html) and [projects](https://libvcs.git-pull.com/en/latest/usage/projects.html).
 :::
 
-## Internals
+::::{grid} 1 2 3 3
+:gutter: 2 2 3 3
 
-:::{warning}
-Be careful with these! Internal APIs are **not** covered by version policies. They can break or be removed between minor versions!
+:::{grid-item-card} vcspull.config
+:link: config
+:link-type: doc
+Configuration loading and repo extraction.
+:::
+
+:::{grid-item-card} vcspull.exc
+:link: exc
+:link-type: doc
+Exception hierarchy.
+:::
 
-If you need an internal API stabilized please [file an issue](https://github.com/vcs-python/vcspull/issues).
+:::{grid-item-card} vcspull.log
+:link: log
+:link-type: doc
+Logging helpers.
 :::
 
+:::{grid-item-card} vcspull.validator
+:link: validator
+:link-type: doc
+Config validation utilities.
+:::
+
+:::{grid-item-card} vcspull.util
+:link: util
+:link-type: doc
+General-purpose utilities.
+:::
+
+:::{grid-item-card} vcspull.types
+:link: types
+:link-type: doc
+Type definitions and aliases.
+:::
+
+::::
+
 ```{toctree}
+:hidden:
+
 config
-cli/index
 exc
 log
-internals/index
 validator
 util
 types

diff --git a/docs/cli/index.md b/docs/cli/index.md
@@ -1,6 +1,73 @@
 (cli)=
 
-# Commands
+(commands)=
+
+# CLI Reference
+
+::::{grid} 1 2 3 3
+:gutter: 2 2 3 3
+
+:::{grid-item-card} vcspull sync
+:link: sync
+:link-type: doc
+Pull / clone repositories from config.
+:::
+
+:::{grid-item-card} vcspull add
+:link: add
+:link-type: doc
+Add a repository to your config file.
+:::
+
+:::{grid-item-card} vcspull list
+:link: list
+:link-type: doc
+List configured repositories.
+:::
+
+:::{grid-item-card} vcspull search
+:link: search
+:link-type: doc
+Search repos by name, path, or URL.
+:::
+
+:::{grid-item-card} vcspull status
+:link: status
+:link-type: doc
+Show working-tree status for each repo.
+:::
+
+:::{grid-item-card} vcspull discover
+:link: discover
+:link-type: doc
+Scan directories for existing repos.
+:::
+
+:::{grid-item-card} vcspull fmt
+:link: fmt
+:link-type: doc
+Normalize and format config files.
+:::
+
+:::{grid-item-card} vcspull import
+:link: import/index
+:link-type: doc
+Import repos from GitHub, GitLab, and more.
+:::
+
+:::{grid-item-card} vcspull worktree
+:link: worktree/index
+:link-type: doc
+Manage git worktrees declaratively.
+:::
+
+:::{grid-item-card} Completion
+:link: completion
+:link-type: doc
+Shell completions for bash, zsh, and fish.
+:::
+
+::::
 
 ```{toctree}
 :caption: General commands

diff --git a/docs/conf.py b/docs/conf.py
@@ -40,9 +40,11 @@
     "sphinx_copybutton",
     "sphinxext.opengraph",
     "sphinxext.rediraffe",
+    "sphinx_design",
     "myst_parser",
     "linkify_issues",
 ]
+myst_heading_anchors = 4
 myst_enable_extensions = [
     "colon_fence",
     "substitution",

diff --git a/docs/configuration/index.md b/docs/configuration/index.md
@@ -2,6 +2,17 @@
 
 # Configuration
 
+::::{grid} 1 1 2 2
+:gutter: 2 2 3 3
+
+:::{grid-item-card} Config Generation
+:link: generation
+:link-type: doc
+Import repos from forges and generate config automatically.
+:::
+
+::::
+
 ## URL Format
 
 Repo type and address is [RFC3986](https://datatracker.ietf.org/doc/html/rfc3986) style URLs.
@@ -260,3 +271,9 @@ For git remotes using SSH authorization such as `git+git@github.com:tony/kaptan.
 ```console
 git+ssh://git@github.com/tony/kaptan.git
 ```
+
+```{toctree}
+:hidden:
+
+generation
+```
diff --git a/docs/index.md b/docs/index.md
@@ -4,37 +4,95 @@ hide-toc: true
 
 (index)=
 
-```{include} ../README.md
-:end-before: <img
-```
+# vcspull
 
-```{image} _static/vcspull-demo.gif
-:width: 100%
+CLI workspace manager for VCS repos. Sync, organize, and manage multiple
+git (and hg/svn) repositories from a single YAML config.
+
+::::{grid} 1 2 3 3
+:gutter: 2 2 3 3
+
+:::{grid-item-card} Quickstart
+:link: quickstart
+:link-type: doc
+Install and sync your first repos.
+:::
+
+:::{grid-item-card} CLI Reference
+:link: cli/index
+:link-type: doc
+Every command, flag, and option.
+:::
+
+:::{grid-item-card} Configuration
+:link: configuration/index
+:link-type: doc
+Config format, locations, schema, and examples.
+:::
+
+::::
+
+::::{grid} 1 1 2 2
+:gutter: 2 2 3 3
+
+:::{grid-item-card} Internals
+:link: internals/index
+:link-type: doc
+Internal Python API for contributors.
+:::
+
+:::{grid-item-card} Contributing
+:link: project/index
+:link-type: doc
+Development setup, code style, and release process.
+:::
+
+::::
+
+## Install
+
+```console
+$ pip install vcspull
 ```
 
-# Donations
+```console
+$ uv tool install vcspull
+```
 
-```{include} ../README.md
-:start-after: "# Donations"
+```console
+$ pipx install vcspull
 ```
 
-```{toctree}
-:maxdepth: 2
-:hidden:
+See [Quickstart](quickstart.md) for all installation methods and first steps.
 
-quickstart
-cli/index
-configuration/index
+## At a glance
+
+```yaml
+~/code/:
+  flask: "git+https://github.com/pallets/flask.git"
+  django: "git+https://github.com/django/django.git"
+~/study/:
+  linux: "git+https://github.com/torvalds/linux.git"
+```
 
+```console
+$ vcspull sync
+```
+
+```{image} _static/vcspull-demo.gif
+:width: 100%
+:loading: lazy
 ```
 
 ```{toctree}
-:caption: Project
 :hidden:
 
+quickstart
+cli/index
+configuration/index
 api/index
-developing
+internals/index
+project/index
 history
 migration
-GitHub <https://github.com/vcs-python/vcspull>
 ```
diff --git a/docs/api/cli/add.md → docs/internals/api/cli/add.md b/docs/api/cli/add.md → docs/internals/api/cli/add.md
diff --git a/docs/api/cli/discover.md → docs/internals/api/cli/discover.md b/docs/api/cli/discover.md → docs/internals/api/cli/discover.md
diff --git a/docs/api/cli/fmt.md → docs/internals/api/cli/fmt.md b/docs/api/cli/fmt.md → docs/internals/api/cli/fmt.md
diff --git a/docs/api/cli/import.md → docs/internals/api/cli/import.md b/docs/api/cli/import.md → docs/internals/api/cli/import.md
diff --git a/docs/api/cli/index.md → docs/internals/api/cli/index.md b/docs/api/cli/index.md → docs/internals/api/cli/index.md
diff --git a/docs/api/cli/list.md → docs/internals/api/cli/list.md b/docs/api/cli/list.md → docs/internals/api/cli/list.md
diff --git a/docs/api/cli/search.md → docs/internals/api/cli/search.md b/docs/api/cli/search.md → docs/internals/api/cli/search.md
diff --git a/docs/api/cli/status.md → docs/internals/api/cli/status.md b/docs/api/cli/status.md → docs/internals/api/cli/status.md
diff --git a/docs/api/cli/sync.md → docs/internals/api/cli/sync.md b/docs/api/cli/sync.md → docs/internals/api/cli/sync.md
diff --git a/docs/api/cli/worktree.md → docs/internals/api/cli/worktree.md b/docs/api/cli/worktree.md → docs/internals/api/cli/worktree.md
diff --git a/docs/api/internals/config_reader.md → docs/internals/api/config_reader.md b/docs/api/internals/config_reader.md → docs/internals/api/config_reader.md
diff --git a/docs/api/internals/index.md → docs/internals/api/index.md b/docs/api/internals/index.md → docs/internals/api/index.md
@@ -1,6 +1,6 @@
-(internals)=
+(internals-api)=
 
-# Internals
+# Internal Python API
 
 :::{warning}
 Be careful with these! Internal APIs are **not** covered by version policies. They can break or be removed between minor versions!

diff --git a/docs/api/internals/private_path.md → docs/internals/api/private_path.md b/docs/api/internals/private_path.md → docs/internals/api/private_path.md
diff --git a/docs/api/internals/worktree_sync.md → docs/internals/api/worktree_sync.md b/docs/api/internals/worktree_sync.md → docs/internals/api/worktree_sync.md
diff --git a/docs/internals/index.md b/docs/internals/index.md
@@ -0,0 +1,36 @@
+(internals)=
+
+# Internals
+
+```{warning}
+Everything in this section is **internal implementation detail**. There is
+no stability guarantee. Interfaces may change or be removed without notice
+between any release.
+
+If you are building workflows with vcspull, use the [CLI](../cli/index.md)
+or refer to the [libvcs API](https://libvcs.git-pull.com/).
+```
+
+::::{grid} 1 1 2 2
+:gutter: 2 2 3 3
+
+:::{grid-item-card} Python API
+:link: api/index
+:link-type: doc
+Internal module reference for contributors and plugin authors.
+:::
+
+:::{grid-item-card} CLI Internals
+:link: api/cli/index
+:link-type: doc
+Python surface behind the CLI commands.
+:::
+
+::::
+
+```{toctree}
+:hidden:
+
+api/index
+api/cli/index
+```
diff --git a/docs/project/code-style.md b/docs/project/code-style.md
@@ -0,0 +1,33 @@
+(code-style)=
+
+# Code Style
+
+## Formatting and linting
+
+vcspull uses [ruff](https://docs.astral.sh/ruff/) for formatting and linting.
+
+```console
+$ uv run ruff format .
+```
+
+```console
+$ uv run ruff check . --fix --show-fixes
+```
+
+## Type checking
+
+[mypy](https://mypy-lang.org/) runs in strict mode.
+
+```console
+$ uv run mypy
+```
+
+## Docstrings
+
+Follow [NumPy docstring convention](https://numpydoc.readthedocs.io/en/latest/format.html).
+
+## Imports
+
+- Use `from __future__ import annotations` in every file.
+- Prefer namespace imports for stdlib: `import pathlib` not `from pathlib import Path`.
+- Use `import typing as t` and access via `t.NamedTuple`, `t.TYPE_CHECKING`, etc.
diff --git a/docs/developing.md → docs/project/contributing.md b/docs/developing.md → docs/project/contributing.md