diff --git a/cmd/zoekt-archive-index/main.go b/cmd/zoekt-archive-index/main.go
index 68817cf9e..999ef134f 100644
--- a/cmd/zoekt-archive-index/main.go
+++ b/cmd/zoekt-archive-index/main.go
@@ -1,6 +1,6 @@
-// Command zoekt-archive-index indexes an archive.
+// Command zoekt-archive-index indexes a git archive.
 //
-// Example via github.com:
+// Examples using github.com:
 //
 //	zoekt-archive-index -incremental -commit b57cb1605fd11ba2ecfa7f68992b4b9cc791934d -name github.com/gorilla/mux -strip_components 1 https://codeload.github.com/gorilla/mux/legacy.tar.gz/b57cb1605fd11ba2ecfa7f68992b4b9cc791934d
 //
diff --git a/cmd/zoekt-dynamic-indexserver/main.go b/cmd/zoekt-dynamic-indexserver/main.go
index fd9244528..e805312f0 100644
--- a/cmd/zoekt-dynamic-indexserver/main.go
+++ b/cmd/zoekt-dynamic-indexserver/main.go
@@ -12,10 +12,10 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// This program manages a zoekt dynamic indexing deployment:
+// Command zoekt-dynamic-indexserver starts a server to manage dynamic indexing. In contrast to
+// zoekt-indexserver, it's designed for a "push-based" indexing model. The server
 // * listens to indexing commands
 // * reindexes specified repositories
-
 package main
 
 import (
diff --git a/cmd/zoekt-git-clone/main.go b/cmd/zoekt-git-clone/main.go
index 7d2150294..ab696b9ee 100644
--- a/cmd/zoekt-git-clone/main.go
+++ b/cmd/zoekt-git-clone/main.go
@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// This binary fetches all repos of a user or organization and clones
+// Command zoekt-git-clone fetches all repos of a user or organization and clones
 // them.  It is strongly recommended to get a personal API token from
 // https://github.com/settings/tokens, save the token in a file, and
 // point the --token option to it.
diff --git a/cmd/zoekt-git-index/main.go b/cmd/zoekt-git-index/main.go
index 12e32c762..e1099e70c 100644
--- a/cmd/zoekt-git-index/main.go
+++ b/cmd/zoekt-git-index/main.go
@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Command zoekt-git-index indexes a single git repository. It works directly with git
+// repositories and supports git-specific features like branches and submodules.
 package main
 
 import (
diff --git a/cmd/zoekt-index/main.go b/cmd/zoekt-index/main.go
index d7fb9cfb2..bd7c4ddca 100644
--- a/cmd/zoekt-index/main.go
+++ b/cmd/zoekt-index/main.go
@@ -12,6 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Command zoekt-index indexes a directory of files.
 package main
 
 import (
diff --git a/cmd/zoekt-indexserver/main.go b/cmd/zoekt-indexserver/main.go
index d31f3bf04..1c1d381ed 100644
--- a/cmd/zoekt-indexserver/main.go
+++ b/cmd/zoekt-indexserver/main.go
@@ -12,11 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// This program manages a zoekt indexing deployment:
-// * recycling logs
-// * periodically fetching new data.
-// * periodically reindexing all git repos.
-
+// Command zoekt-indexserver starts a service that periodically reindexes repositories. It follows
+// a "pull-based" design, where it reaches out to code hosts to fetch new data.
 package main
 
 import (
diff --git a/cmd/zoekt-merge-index/main.go b/cmd/zoekt-merge-index/main.go
index 3221ea50f..0f72acd14 100644
--- a/cmd/zoekt-merge-index/main.go
+++ b/cmd/zoekt-merge-index/main.go
@@ -1,3 +1,16 @@
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Command zoekt-merge-index merges a set of index shards into a compound shard.
 package main
 
 import (
diff --git a/cmd/zoekt-mirror-bitbucket-server/main.go b/cmd/zoekt-mirror-bitbucket-server/main.go
index 5b2cdcfde..76b57507c 100644
--- a/cmd/zoekt-mirror-bitbucket-server/main.go
+++ b/cmd/zoekt-mirror-bitbucket-server/main.go
@@ -10,9 +10,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// This binary fetches all repos of a project, and of a specific type, in case
-// these are specified, and clones them. By default it fetches and clones all
-// existing repos.
+// Command zoekt-mirror-bitbucket-server fetches all repos of a bitbucket project,
+// optionally of a specific type, and clones them.
 package main
 
 import (
diff --git a/cmd/zoekt-mirror-gerrit/main.go b/cmd/zoekt-mirror-gerrit/main.go
index d786a8586..b42d81449 100644
--- a/cmd/zoekt-mirror-gerrit/main.go
+++ b/cmd/zoekt-mirror-gerrit/main.go
@@ -12,8 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// This binary fetches all repos of a Gerrit host.
-
+// Command zoekt-mirror-gerrit fetches all repos of a Gerrit host.
 package main
 
 import (
diff --git a/cmd/zoekt-mirror-gitea/main.go b/cmd/zoekt-mirror-gitea/main.go
index 81eeafb4b..e946aa93d 100644
--- a/cmd/zoekt-mirror-gitea/main.go
+++ b/cmd/zoekt-mirror-gitea/main.go
@@ -12,10 +12,10 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// This binary fetches all repos of a user or organization and clones
-// them.  It is strongly recommended to get a personal API token from
-// https://gitea.com/user/settings/applications, save the token in a
-// file, and point the --token option to it.
+// Command zoekt-mirror-gerrit fetches all repos of a gitea user or organization
+// and clones them. It is strongly recommended to get a personal API token from
+// https://gitea.com/user/settings/applications, save the token in a file, and point
+// the --token option to it.
 package main
 
 import (
diff --git a/cmd/zoekt-mirror-github/main.go b/cmd/zoekt-mirror-github/main.go
index 0a8469726..3aa3d6dde 100644
--- a/cmd/zoekt-mirror-github/main.go
+++ b/cmd/zoekt-mirror-github/main.go
@@ -12,10 +12,10 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// This binary fetches all repos of a user or organization and clones
-// them.  It is strongly recommended to get a personal API token from
-// https://github.com/settings/tokens, save the token in a file, and
-// point the --token option to it.
+// Command zoekt-mirror-github fetches all repos of a github user or organization
+// and clones them. It is strongly recommended to get a personal API token from
+// https://github.com/settings/tokens, save the token in a file, and point the
+// --token option to it.
 package main
 
 import (
diff --git a/cmd/zoekt-mirror-gitiles/main.go b/cmd/zoekt-mirror-gitiles/main.go
index cba93e5cb..024796395 100644
--- a/cmd/zoekt-mirror-gitiles/main.go
+++ b/cmd/zoekt-mirror-gitiles/main.go
@@ -12,8 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// This binary fetches all repos of a Gitiles host.  It does double
-// duty for other "simple" web hosts
+// Command zoekt-mirror-gitiles fetches all repos of a Gitiles host.
+// It does double duty for other "simple" web hosts.
 package main
 
 import (
diff --git a/cmd/zoekt-mirror-gitlab/main.go b/cmd/zoekt-mirror-gitlab/main.go
index d2f169985..60030c446 100644
--- a/cmd/zoekt-mirror-gitlab/main.go
+++ b/cmd/zoekt-mirror-gitlab/main.go
@@ -10,13 +10,13 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// This binary fetches all repos for a user from gitlab.
+// Command zoekt-mirror-gitlab fetches all repos for a user from gitlab.
 //
 // It is recommended to use a gitlab personal access token:
 // https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html. This
 // token should be stored in a file and the --token option should be used.
 // In addition, the token should be present in the ~/.netrc of the user running
-// the mirror command. For example, the ~/.netrc may look like:
+// Command mirror. For example, the ~/.netrc may look like:
 //
 //	machine gitlab.com
 //	login oauth
diff --git a/cmd/zoekt-repo-index/main.go b/cmd/zoekt-repo-index/main.go
index f5e3970d1..3f046aec5 100644
--- a/cmd/zoekt-repo-index/main.go
+++ b/cmd/zoekt-repo-index/main.go
@@ -12,9 +12,10 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// zoekt-repo-index indexes a repo-based repository. The constituent git
+// Command zoekt-repo-index indexes repository that uses the Android 'repo'
+// tool (https://android.googlesource.com/tools/repo). The constituent git
 // repositories should already have been downloaded to the --repo_cache
-// directory, eg.
+// directory, for example:
 //
 // go install github.com/sourcegraph/zoekt/cmd/zoekt-repo-index &&
 //
diff --git a/cmd/zoekt-sourcegraph-indexserver/main.go b/cmd/zoekt-sourcegraph-indexserver/main.go
index de3d13658..8e584a508 100644
--- a/cmd/zoekt-sourcegraph-indexserver/main.go
+++ b/cmd/zoekt-sourcegraph-indexserver/main.go
@@ -1,5 +1,18 @@
-// Command zoekt-sourcegraph-indexserver periodically reindexes enabled
-// repositories on sourcegraph
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Command zoekt-sourcegraph-indexserver periodically reindexes repositories
+// from a Sourcegraph instance. It uses a "pull-based" design, where it periodically
+// reaches out to the Sourcegraph instance for the list of repositories to reindex.
 package main
 
 import (
diff --git a/cmd/zoekt-test/main.go b/cmd/zoekt-test/main.go
index 5de3f26a3..4a4c17855 100644
--- a/cmd/zoekt-test/main.go
+++ b/cmd/zoekt-test/main.go
@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// zoekt-test compares the search engine results with raw substring search
+// Command zoekt-test compares the zoekt results with raw substring search.
 package main
 
 import (
diff --git a/cmd/zoekt-webserver/main.go b/cmd/zoekt-webserver/main.go
index bd2f30873..4f4e2b2ae 100644
--- a/cmd/zoekt-webserver/main.go
+++ b/cmd/zoekt-webserver/main.go
@@ -12,9 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// Command zoekt-webserver responds to search queries, using an index generated
-// by another program such as zoekt-indexserver.
-
+// Command zoekt-webserver starts a server that responds to search queries, using
+// an index generated by another program such as zoekt-indexserver.
 package main
 
 import (
diff --git a/cmd/zoekt/main.go b/cmd/zoekt/main.go
index 78179bee9..d1c06eae7 100644
--- a/cmd/zoekt/main.go
+++ b/cmd/zoekt/main.go
@@ -12,6 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// The 'zoekt' command supports searching over an index directory or shard.
 package main
 
 import (
diff --git a/ignore/ignore.go b/ignore/ignore.go
index 4782a5658..fdb141eb5 100644
--- a/ignore/ignore.go
+++ b/ignore/ignore.go
@@ -1,3 +1,15 @@
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 // Package ignore provides helpers to support ignore-files similar to .gitignore
 package ignore
 
diff --git a/index/builder.go b/index/builder.go
index 4ac018fc0..ff452291f 100644
--- a/index/builder.go
+++ b/index/builder.go
@@ -12,8 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// package build implements a more convenient interface for building
-// zoekt indices.
+// Package index contains logic for building Zoekt indexes. NOTE: this package is not considered
+// part of the public API, and it is not recommended to rely on it in external code.
 package index
 
 import (
diff --git a/query/doc.go b/query/doc.go
new file mode 100644
index 000000000..7a922e89a
--- /dev/null
+++ b/query/doc.go
@@ -0,0 +1,16 @@
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package query contains the API for creating Zoekt queries. Queries can be
+// constructed directly through query.Q objects, or by parsing a string using
+// query.Parse
+package query
diff --git a/web/doc.go b/web/doc.go
new file mode 100644
index 000000000..dfb80185e
--- /dev/null
+++ b/web/doc.go
@@ -0,0 +1,15 @@
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package web contains the logic for spinning up a zoekt webserver. It's exposed separately
+// from zoekt-webserver to allow for customizing the endpoints and format templates.
+package web