Feat/vitepress docs

[shouze]

What does this PR do?

Fixes #24

[github-actions]

Coverage after merging feat/vitepress-docs into main will be

96.41%

Coverage Report

File	Stmts	Branches	Funcs	Lines	Uncovered Lines
src
aggregate.ts	100%	100%	100%	100%
api-utils.ts	97.50%	100%	100%	97.18%	52, 60
api.ts	93.43%	100%	100%	92.51%	235–239, 295, 312, 63–69
cache.ts	98.08%	100%	100%	97.87%	28
group.ts	100%	100%	100%	100%
output.ts	99.12%	100%	94.74%	99.52%	58
render.ts	97.20%	100%	100%	97.14%	142–145
upgrade.ts	77.01%	100%	88.89%	75.64%	128, 130–132, 79–93
src/render
filter.ts	100%	100%	100%	100%
highlight.ts	99.29%	100%	100%	99.01%	184–185
rows.ts	100%	100%	100%	100%
selection.ts	100%	100%	100%	100%
summary.ts	100%	100%	100%	100%

[Copilot]

Pull request overview

This PR implements a comprehensive VitePress documentation site as specified in issue #24. The migration consolidates the 470-line README into a well-structured documentation site with proper navigation, versioning support, and architecture diagrams while reducing the README to 17 lines with a link to the full docs.

Changes:

• Adds VitePress documentation infrastructure with custom theme, Mermaid diagram support, and versioning
• Migrates all README content to organized docs structure (Getting Started, Usage, Reference, Architecture)
• Implements GitHub Actions workflow for automated deployment to GitHub Pages with versioned snapshot support
• Updates project configuration files (package.json, knip.json, .gitignore) for docs tooling
• Adds documentation guidelines for contributors in AGENTS.md and instruction files

Reviewed changes

Copilot reviewed 33 out of 43 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
package.json	Adds VitePress, Mermaid, and related dependencies; adds docs:dev, docs:build, docs:preview scripts
knip.json	Ignores docs/** directory and VitePress-related dependencies from unused exports checking
.gitignore	Excludes VitePress build artifacts (cache and dist directories)
docs/.vitepress/config.mts	VitePress configuration with navigation, sidebar, versioning dropdown, and site metadata
docs/.vitepress/theme/index.ts	Custom theme extending VitePress default with Mermaid renderer and terminal demo component
docs/.vitepress/theme/custom.css	Brand styling with Fulll color palette, Poppins font, and responsive design
docs/.vitepress/theme/TerminalDemo.vue	Animated terminal demo component for hero section
docs/index.md	Landing page with hero section and feature cards
docs/getting-started/*.md	Prerequisites, installation, and first search guides
docs/usage/*.md	Seven usage guides covering search syntax, modes, formats, filtering, grouping, and upgrades
docs/reference/*.md	Reference documentation for CLI options, shortcuts, API limits, and environment variables
docs/architecture/*.md	C4 architecture diagrams (Levels 1-3) documenting system structure
docs/public/*	Static assets including favicons, icons, and versions.json for version dropdown
.github/workflows/docs.yml	CI/CD workflow for deploying docs to GitHub Pages with versioned snapshot support
README.md	Slimmed down to 17 lines with badges and link to full documentation site
AGENTS.md	Adds Git conventions section documenting signed commit requirements
.github/instructions/*.instructions.md	Updates instruction files with signed commit requirements and adds new documentation guidelines

[Copilot]

The version dropdown creates links using relative paths like "/v2/" (line 190 in workflow). However, the VitePress site is deployed at /github-code-search/ (base URL), so a link to "/v2/" would navigate to the site root /v2/ instead of /github-code-search/v2/ where the snapshot is actually deployed. The LINK variable should be "/github-code-search/${MAJOR}/" to create correct absolute paths that work with the configured base URL.

Suggested change

	LINK="/${MAJOR}/"
	LINK="/github-code-search/${MAJOR}/"

[Copilot]

The workflow combines branches and tags under a single push event with a paths filter. In GitHub Actions, paths filters apply to both branches and tags when combined. This means pushing a major version tag (v2.0.0) will only trigger the snapshot job if the tagged commit modified docs/** or the workflow file. If tags are created on commits without doc changes (e.g., after a version bump commit), the snapshot job won't run. Consider separating into two push events: one for branches with paths filter, and one for tags without paths filter to ensure version tags always trigger snapshots.

Suggested change

	paths:
	- "docs/**"
	- ".github/workflows/docs.yml"

[Copilot]

The documentation instructions file (line 77) refers to vitepress-plugin-mermaid but the actual package installed in package.json is vitepress-mermaid-renderer. The documentation should be updated to match the actual package name being used, or vice versa. This discrepancy could confuse contributors.

Suggested change

	- Use `vitepress-plugin-mermaid` — wrap diagrams in ` ```mermaid ` fenced blocks.
	- Use `vitepress-mermaid-renderer` — wrap diagrams in ` ```mermaid ` fenced blocks.

[Copilot]

Lines 139-140 state that commits pushed via the GitHub API "are automatically Verified by GitHub" and that agents should avoid using MCP REST API push tools. However, this contradicts the requirement stated in AGENTS.md lines 137-141 which explicitly says commits signed by GitHub's key (like those from REST API pushes) do NOT carry the developer's identity and should be avoided. The instructions files should consistently state that ALL commits must be locally signed with the developer's GPG/SSH key, not GitHub's key.

Suggested change

	Commits pushed via the GitHub API (Copilot Coding Agent, MCP tools) are automatically Verified by GitHub.
	Commits must be created and signed locally with your own GPG/SSH key; do **not** use GitHub API / REST-based push tools (including Copilot Coding Agent or MCP tools) that produce commits signed by GitHub’s key.

[Copilot]

Lines 69-70 state that commits pushed via the GitHub API "are automatically Verified by GitHub" which contradicts the signed commit requirement documented in AGENTS.md lines 137-141. The AGENTS.md explicitly says commits signed by GitHub's key (from REST API pushes) do NOT carry the developer's identity and should NOT be used. This instruction should be updated to align with the requirement that all commits must be locally signed with the developer's own GPG/SSH key.

Suggested change

	- **All commits must be signed** (GPG or SSH). Configure once with `git config --global commit.gpgsign true`.
	Commits pushed via the GitHub API (Copilot Coding Agent, MCP tools) are automatically Verified by GitHub.
	- **All commits must be signed** (GPG or SSH) with your own key. Configure once with `git config --global commit.gpgsign true`.
	Commits created via the GitHub API (Copilot Coding Agent, MCP tools) are signed with GitHub’s key and do **not** satisfy this requirement; do not use them for feature work in this repository.

[Copilot]

Lines 78-79 state that commits pushed via the GitHub API "are automatically Verified by GitHub" which contradicts the signed commit requirement documented in AGENTS.md lines 137-141. The AGENTS.md explicitly says commits signed by GitHub's key (from REST API pushes) do NOT carry the developer's identity and should NOT be used. This instruction should be updated to align with the requirement that all commits must be locally signed with the developer's own GPG/SSH key.

Suggested change

	- **All commits must be signed** (GPG or SSH). Configure once with `git config --global commit.gpgsign true`.
	Commits pushed via the GitHub API (Copilot Coding Agent, MCP tools) are automatically Verified by GitHub.
	- **All commits must be locally signed with your own GPG or SSH key.** Configure once with `git config --global commit.gpgsign true`.
	Do **not** rely on commits signed by GitHub’s key (for example, commits created via the GitHub REST API, Copilot Coding Agent, or MCP tools); these do not carry your developer identity and do **not** satisfy this requirement.

[Copilot]

The number "1 000" uses space-separated formatting, but according to stored codebase conventions, comma-separated formatting "1,000" should be used instead in documentation. This convention is established to maintain consistency across all documentation.

Suggested change

	`github-code-search` fetches all matching code items across your organisation (up to 1 000 results) and opens the **interactive TUI**.
	`github-code-search` fetches all matching code items across your organisation (up to 1,000 results) and opens the **interactive TUI**.

[Copilot]

The workflow uses stefanzweifel/git-auto-commit-action@v5.0.1 which creates commits that are signed by GitHub's key, not the developer's personal key. This violates the signed commit requirement documented in AGENTS.md lines 137-141 which explicitly states commits signed by GitHub's key do NOT carry the developer's identity and should be avoided. Consider using a local git commit approach instead, or document this as an exception for CI-created commits.

Suggested change

	uses: stefanzweifel/git-auto-commit-action@v5.0.1
	with:
	# No [skip ci] — the push to main matches paths: docs/** and re-triggers
	# the deploy job, which merges the new snapshot into the Pages artifact.
	commit_message: "docs: add ${{ steps.ver.outputs.major }} to versions.json"
	file_pattern: docs/public/versions.json
	branch: main
	# Use a local git commit instead of git-auto-commit-action to avoid
	# commits signed with GitHub's global key. These CI commits are an
	# explicit exception for generated docs metadata (see AGENTS.md).
	run: |
	MAJOR="${{ steps.ver.outputs.major }}"
	git config user.name "github-actions[bot]"
	git config user.email "github-actions[bot]@users.noreply.github.com"
	git add docs/public/versions.json
	# Only create a commit if there are staged changes.
	if ! git diff --cached --quiet; then
	git commit -m "docs: add ${MAJOR} to versions.json"
	# No [skip ci] — the push to main matches paths: docs/** and re-triggers
	# the deploy job, which merges the new snapshot into the Pages artifact.
	git push origin HEAD:main
	fi