docs: add community guides and link the documentation site

AGENTS.md

@@ -4,7 +4,7 @@ This repository contains Context Source Graph: Go HTTP/MCP services, Git/Zoekt i
 
 - Keep source, fixtures, documentation, skills, and artifacts suitable for public distribution.
 - Read README.md and docs/README.md before changes. Update documentation with behavior.
-- Run Go tests for affected packages, `bun run check:web`, and the production build.
+- Run `bun run check` (gofmt, `go vet` and web checks), Go tests for affected packages, and the production build.
 - Persist control state and identity changes before acknowledging success. Preserve revision, lease, and generation checks.
 - Never commit credentials, environment files, databases, indexes, or generated build output.
 - Each instance exclusively owns its repositories and persistent storage. Supported topologies are a single large-disk instance, or sharded instances sharing one database behind repository-key sticky routing configured at the access layer (see `docs/deployment.md`). Never let two instances serve the same repository or share a data directory.

CODE_OF_CONDUCT.md

@@ -0,0 +1,29 @@
+# Contributor Covenant Code of Conduct
+
+## Our pledge
+
+We pledge to make participation in this project a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socioeconomic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- demonstrating empathy and kindness toward other people;
+- respecting differing opinions, viewpoints, and experiences;
+- giving and gracefully accepting constructive feedback;
+- accepting responsibility and apologizing to those affected by mistakes;
+- focusing on what is best for the community.
+
+Examples of unacceptable behavior include harassment, insults, sexualized attention, publishing private information without permission, and conduct that would reasonably be considered inappropriate in a professional setting.
+
+## Enforcement and scope
+
+Maintainers may remove, edit, or reject contributions and participation that do not align with this Code of Conduct. It applies in project spaces and whenever an individual officially represents the project.
+
+Report unacceptable behavior confidentially through the repository's [private reporting form](https://github.com/context4ai/sourcegraph/security/advisories/new). Prefix the report title with `[Code of Conduct]`.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html), available under the [Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/).

CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# Contributing to Context Source Graph
+
+Thank you for helping improve Context Source Graph. Contributions can include
+bug reports, documentation, search and read behavior, MCP and HTTP interfaces,
+repository plugins, deployment guidance and tests.
+
+## Before opening a pull request
+
+- Search existing Issues and Discussions first.
+- Discuss changes to public HTTP, MCP or CLI contracts, storage layout,
+  authentication or the repository plugin ABI in an Issue or Discussion before
+  implementation.
+- Small documentation fixes and isolated bug fixes can go directly to a pull
+  request.
+- Report security vulnerabilities privately by following [SECURITY.md](SECURITY.md).
+
+## Development setup
+
+```sh
+git clone https://github.com/context4ai/sourcegraph.git
+cd sourcegraph
+bun install --frozen-lockfile
+bun run build:web
+bun run check
+go test -p 1 ./...
+```
+
+[DEVELOPMENT.md](DEVELOPMENT.md) covers prerequisites, running a local
+instance and configuration. The concepts behind the service are explained in
+the [Source Graph documentation](https://context4ai.org/context/pages/e1ce6ff3105ae09d13eec7cbe39ae133.html).
+
+## Pull request expectations
+
+A change is ready for review when:
+
+- `bun run check`, the Go tests for affected packages and `bun run build` pass;
+- documentation under `docs/` and both README files reflect the behavior;
+- browser, HTTP, MCP and CLI surfaces stay consistent for a shared operation;
+- control state and identity changes are persisted before success is reported;
+- fixtures and examples use public repositories only;
+- credentials, environment files, databases, indexes and build output are not
+  committed.
+
+Keep pull requests focused. Explain the problem, observable behavior,
+compatibility impact and verification evidence.
+
+## Commit messages
+
+Use an English conventional commit:
+
+```text
+feat: add read_many to the MCP server
+fix: isolate unsupported Git paths during indexing
+docs: link the documentation site
+```
+
+## Conduct
+
+Participation is governed by the [Code of Conduct](CODE_OF_CONDUCT.md).

DEVELOPMENT.md

@@ -42,10 +42,13 @@ CI runs the same verification on pull requests and `main`; see `.github/workflow
 | `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` | Google web OAuth client |
 | `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET` | GitHub OAuth app |
 
+Repository read plugins are tuned with `SOURCEGRAPH_PLUGINS_*`; see [repository plugins](docs/ref/repository-plugins.md). The CLI reads `SOURCEGRAPH_URL` and `SOURCEGRAPH_API_TOKEN`; see [interfaces](docs/interfaces.md#cli).
+
 Never put credentials in deployment JSON, source code or images. Public non-secret defaults live in `config/deployment.json`.
 
 ## Further reading
 
+- [Self-Hosting](https://context4ai.org/context/pages/87e9a0f083fa7c393fae3f5bbb123a11.html) and [Operations](https://context4ai.org/context/pages/b6b5d0b7d4370275aa82611da7136e4f.html) — guides on the documentation site
 - [Interfaces](docs/interfaces.md) — HTTP routes, MCP and CLI
 - [Deployment](docs/deployment.md) — Fly.io, databases, backups and recovery
 - [Repository plugins](docs/ref/repository-plugins.md) — Wasm plugin contract

README.md

@@ -2,7 +2,7 @@
 
 **Millisecond code search and reading at pinned Git revisions — for people, scripts and AI agents.**
 
-[Live demo](https://context4ai.org/sourcegraph/) · [Documentation](docs/README.md) · [Development](DEVELOPMENT.md) · [简体中文](README.zh-CN.md)
+[Live demo](https://context4ai.org/sourcegraph/) · [Documentation](https://context4ai.org/context/pages/e1ce6ff3105ae09d13eec7cbe39ae133.html) · [Reference docs](docs/README.md) · [Contributing](CONTRIBUTING.md) · [简体中文](README.zh-CN.md)
 
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 ![Go](https://img.shields.io/badge/Go-1.26%2B-00ADD8?logo=go&logoColor=white)
@@ -19,7 +19,7 @@ It is built for the workload AI coding agents generate: many small, precise `sea
 
 - **Milliseconds, not seconds.** Indexed search typically completes in **under 5 ms** on the server. Deployed in the same region as its callers, a full request — network included — stays **well under 100 ms**, which is faster than running `grep` or `rg` over a local checkout.
 - **Reproducible answers.** Branches and tags resolve to a commit before anything is read, so a search result, the file it points to and a later diff all refer to the same snapshot.
-- **One contract, four surfaces.** Browser, HTTP, MCP and CLI share the same operations: `repositories`, `availability`, `resolve`, `search`, `read`, `read_many`, `list`, `diff` and `prepare`.
+- **One contract, four surfaces.** Browser, HTTP, MCP and CLI share the same operations: `repositories`, `availability`, `resolve`, `search`, `read`, `list`, `diff` and `prepare`. MCP adds `read_many` for several reads in one call. See [interfaces](docs/interfaces.md).
 - **Agent-ready.** A stateless Streamable HTTP MCP endpoint works with any MCP client; anonymous access is read-only and limited to public repositories.
 - **Small footprint.** One process manages Git mirrors, the Zoekt child process and background indexing. SQLite by default; PostgreSQL and MongoDB are supported.
 - **Extensible reads.** Repositories can ship Wasm plugins (`<name>.sourcegraph.wasm`) that change how `read` and `read_many` present files. See [repository plugins](docs/ref/repository-plugins.md).
@@ -94,6 +94,16 @@ Fly.io configuration, databases, backups and recovery are covered in [deployment
 
 ## Documentation
 
+The [Source Graph documentation](https://context4ai.org/context/pages/e1ce6ff3105ae09d13eec7cbe39ae133.html) on the Context site covers the concepts and day-to-day use:
+
+| Section | Pages |
+| --- | --- |
+| How It Works | [Overview](https://context4ai.org/context/pages/e1ce6ff3105ae09d13eec7cbe39ae133.html) · [Pinned Search and Reads](https://context4ai.org/context/pages/9b8f7c105b990cf29a3a7936dc0ff462.html) · [Evidence for Context](https://context4ai.org/context/pages/3bbf57d3dcee4b0ea0433d3b367cc045.html) |
+| Guides | [Connecting](https://context4ai.org/context/pages/ef2f49d8f38697ceb1f7aaa88deba84d.html) · [Self-Hosting](https://context4ai.org/context/pages/87e9a0f083fa7c393fae3f5bbb123a11.html) · [Registering Repositories](https://context4ai.org/context/pages/aa50227a56841f0d42fe08e9dfa4cd53.html) · [Authentication and Access Control](https://context4ai.org/context/pages/1388f44bd0735b535af45b2eefc03e30.html) · [Operations](https://context4ai.org/context/pages/b6b5d0b7d4370275aa82611da7136e4f.html) |
+| Reference | [CLI](https://context4ai.org/context/pages/7b5a8c8039ac425e57fbaeb65690b5b6.html) · [Configuration](https://context4ai.org/context/pages/8165da3ea04839f9d9684e308d054177.html) · [HTTP and MCP](https://context4ai.org/context/pages/a8fe02c341a72e370f653228d71e9982.html) · [Query Syntax](https://context4ai.org/context/pages/e6f59a794ecd01b09dc543afbc9f5da1.html) |
+
+The reference documents in this repository describe the current implementation:
+
 | | |
 | --- | --- |
 | [Authentication](docs/authentication.md) | Google / GitHub sign-in, administrator bootstrap, registration policy |
@@ -106,4 +116,8 @@ Fly.io configuration, databases, backups and recovery are covered in [deployment
 
 [MIT](LICENSE). Context Source Graph uses Zoekt (Apache-2.0) and other open-source components; see [NOTICE](NOTICE). The project name does not imply affiliation with the Sourcegraph platform.
 
-Part of [Context](https://github.com/context4ai/context).
+## Ecosystem and contributing
+
+Source Graph is part of [Context for AI](https://context4ai.org). [Context](https://github.com/context4ai/context) reads code evidence through it remotely ([Evidence for Context](https://context4ai.org/context/pages/3bbf57d3dcee4b0ea0433d3b367cc045.html)), and [Portal](https://github.com/context4ai/portal) serves it at `/sourcegraph/`.
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. Ask questions in [GitHub Discussions](https://github.com/context4ai/sourcegraph/discussions) (see [SUPPORT.md](SUPPORT.md)) and report vulnerabilities through [SECURITY.md](SECURITY.md). Participation is governed by the [Code of Conduct](CODE_OF_CONDUCT.md).

README.zh-CN.md

@@ -2,7 +2,7 @@
 
 **在固定 Git 版本上毫秒级搜索与阅读代码 —— 面向人、脚本与 AI Agent。**
 
-[在线演示](https://context4ai.org/sourcegraph/) · [文档](docs/README.md) · [开发指南](DEVELOPMENT.md) · [English](README.md)
+[在线演示](https://context4ai.org/sourcegraph/) · [文档](https://context4ai.org/context/pages/e1ce6ff3105ae09d13eec7cbe39ae133.html) · [参考文档](docs/README.md) · [参与贡献](CONTRIBUTING.md) · [English](README.md)
 
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 ![Go](https://img.shields.io/badge/Go-1.26%2B-00ADD8?logo=go&logoColor=white)
@@ -19,7 +19,7 @@ Context Source Graph 是一个可自托管的代码搜索服务，基于 Go、Gi
 
 - **毫秒级，而不是秒级。** 基于索引的搜索在服务端通常 **5 ms 以内** 完成。与调用方部署在同一机房时，包含网络在内的完整请求也能 **远低于 100 ms**，比在本地检出目录里跑 `grep` 或 `rg` 更快。
 - **结果可复现。** 分支和标签在读取前先解析为 commit，搜索结果、它指向的文件以及之后的 diff 都对应同一个快照。
-- **一套契约，四种入口。** 浏览器、HTTP、MCP 与 CLI 共享相同的操作：`repositories`、`availability`、`resolve`、`search`、`read`、`read_many`、`list`、`diff` 和 `prepare`。
+- **一套契约，四种入口。** 浏览器、HTTP、MCP 与 CLI 共享相同的操作：`repositories`、`availability`、`resolve`、`search`、`read`、`list`、`diff` 和 `prepare`；MCP 另有 `read_many`，一次调用读取多处。详见[接口](docs/interfaces.md)。
 - **为 Agent 而生。** 无状态的 Streamable HTTP MCP 端点可接入任意 MCP 客户端；匿名访问只读，且仅限公开仓库。
 - **轻量。** 单个进程即可管理 Git 镜像、Zoekt 子进程和后台索引。默认使用 SQLite，同时支持 PostgreSQL 与 MongoDB。
 - **可扩展的读取。** 仓库可以自带 Wasm 插件（`<name>.sourcegraph.wasm`），定制 `read` 与 `read_many` 的文件呈现方式，详见[仓库插件](docs/ref/repository-plugins.md)。
@@ -94,6 +94,16 @@ Fly.io 配置、数据库、备份与恢复见[部署文档](docs/deployment.md)
 
 ## 文档
 
+Context 文档站的 [Source Graph 文档](https://context4ai.org/context/pages/e1ce6ff3105ae09d13eec7cbe39ae133.html)介绍概念与日常使用（与英文共用地址，按语言偏好显示中文）：
+
+| 分类 | 页面 |
+| --- | --- |
+| 原理 | [概览](https://context4ai.org/context/pages/e1ce6ff3105ae09d13eec7cbe39ae133.html) · [固定版本的搜索与阅读](https://context4ai.org/context/pages/9b8f7c105b990cf29a3a7936dc0ff462.html) · [为 Context 提供证据](https://context4ai.org/context/pages/3bbf57d3dcee4b0ea0433d3b367cc045.html) |
+| 指南 | [连接](https://context4ai.org/context/pages/ef2f49d8f38697ceb1f7aaa88deba84d.html) · [自行部署](https://context4ai.org/context/pages/87e9a0f083fa7c393fae3f5bbb123a11.html) · [登记仓库](https://context4ai.org/context/pages/aa50227a56841f0d42fe08e9dfa4cd53.html) · [认证与访问控制](https://context4ai.org/context/pages/1388f44bd0735b535af45b2eefc03e30.html) · [运维](https://context4ai.org/context/pages/b6b5d0b7d4370275aa82611da7136e4f.html) |
+| 参考 | [CLI](https://context4ai.org/context/pages/7b5a8c8039ac425e57fbaeb65690b5b6.html) · [配置](https://context4ai.org/context/pages/8165da3ea04839f9d9684e308d054177.html) · [HTTP 与 MCP](https://context4ai.org/context/pages/a8fe02c341a72e370f653228d71e9982.html) · [查询语法](https://context4ai.org/context/pages/e6f59a794ecd01b09dc543afbc9f5da1.html) |
+
+本仓库的参考文档描述当前实现：
+
 | | |
 | --- | --- |
 | [认证](docs/authentication.md) | Google / GitHub 登录、管理员初始化、注册策略 |
@@ -106,4 +116,8 @@ Fly.io 配置、数据库、备份与恢复见[部署文档](docs/deployment.md)
 
 [MIT](LICENSE)。Context Source Graph 使用了 Zoekt（Apache-2.0）及其他开源组件，详见 [NOTICE](NOTICE)。项目名称不代表与 Sourcegraph 平台存在任何关联。
 
-本项目是 [Context](https://github.com/context4ai/context) 的一部分。
+## 生态与参与贡献
+
+Source Graph 是 [Context for AI](https://context4ai.org) 的一部分。[Context](https://github.com/context4ai/context) 通过它远程读取代码证据（[为 Context 提供证据](https://context4ai.org/context/pages/3bbf57d3dcee4b0ea0433d3b367cc045.html)），[Portal](https://github.com/context4ai/portal) 在 `/sourcegraph/` 下提供它。
+
+提交 Pull Request 前请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。使用问题请到 [GitHub Discussions](https://github.com/context4ai/sourcegraph/discussions)（见 [SUPPORT.md](SUPPORT.md)），安全漏洞按 [SECURITY.md](SECURITY.md) 报告。参与本项目须遵守[行为准则](CODE_OF_CONDUCT.md)。

SECURITY.md

@@ -0,0 +1,26 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are applied to the `main` branch, which is what the public demo
+runs.
+
+## Reporting a vulnerability
+
+Do not open a public Issue for a suspected vulnerability. Use GitHub's
+[private vulnerability reporting](https://github.com/context4ai/sourcegraph/security/advisories/new)
+and include:
+
+- the affected commit or deployment and component;
+- reproduction steps or a proof of concept;
+- the security impact;
+- any suggested mitigation;
+- whether the issue has been disclosed elsewhere.
+
+Relevant reports include authentication or authorization bypasses, access to
+private repositories without permission, credential disclosure, path traversal,
+unsafe Git or plugin execution, cross-site scripting or request forgery, and
+denial of service through crafted queries or repositories.
+
+General support questions and non-security bugs should use GitHub Discussions
+or Issues.

SUPPORT.md

@@ -0,0 +1,16 @@
+# Support
+
+Choose the channel that matches the request:
+
+- Read the [Source Graph documentation](https://context4ai.org/context/pages/e1ce6ff3105ae09d13eec7cbe39ae133.html)
+  and the [reference docs](docs/README.md) in this repository.
+- Use [GitHub Discussions](https://github.com/context4ai/sourcegraph/discussions)
+  for usage, deployment and integration questions.
+- Open an [Issue](https://github.com/context4ai/sourcegraph/issues/new) for
+  reproducible defects.
+- Follow [SECURITY.md](SECURITY.md) for vulnerabilities.
+
+When asking for help, include the commit or image you run, the database and
+topology, the surface you used (browser, HTTP, MCP or CLI), the request and
+sanitized logs. Do not publish credentials, OAuth secrets, API tokens or the
+contents of private repositories.

docs/authentication.md

@@ -6,12 +6,12 @@ The site setting **Allow other users to sign in or register** defaults to off. A
 
 ## Demo callback addresses
 
-The initial service origin is `https://context4ai-sourcegraph.fly.dev`.
+Callbacks are `SOURCEGRAPH_ORIGIN` followed by `/sourcegraph/auth/google/callback` or `/sourcegraph/auth/github/callback`. The demo is published at `https://context4ai.org/sourcegraph/` through the portal, while its `SOURCEGRAPH_ORIGIN` is still the App hostname `https://context4ai-sourcegraph.fly.dev`:
 
 - Google: `https://context4ai-sourcegraph.fly.dev/sourcegraph/auth/google/callback`
 - GitHub: `https://context4ai-sourcegraph.fly.dev/sourcegraph/auth/github/callback`
 
-Use the same origin in `SOURCEGRAPH_ORIGIN`. When the portal becomes the public entry point, update this setting and the provider callbacks together. For the planned custom domain, use `https://context4ai.org/sourcegraph/auth/google/callback` and `https://context4ai.org/sourcegraph/auth/github/callback`.
+To sign in through the portal domain, change `SOURCEGRAPH_ORIGIN` to `https://context4ai.org` and update both provider callbacks to `https://context4ai.org/sourcegraph/auth/google/callback` and `https://context4ai.org/sourcegraph/auth/github/callback` at the same time.
 
 ## Create Google credentials