# Git Search Tool – Design

## Purpose

A small, dependency-free PHP/CLI documentation browser for the Git notes, FAQs, cheatsheets, and task guides developed for this project.

It supports:

- Grouped browsing by topic.
- Expand/collapse per item.
- Expand all and collapse all.
- Full-text search across titles, tags, questions, answers, and command snippets.
- Topic and document-type filtering.
- A CLI interface for listing, searching, and viewing content.
- Static JSON data files that can be regenerated or edited without changing the UI.

## Folder structure

```text
git-search-tool/
├── README.md
├── docs/
│   ├── faq1.md ... faq5.md
│   ├── git1.md
│   ├── git.cheatsheet.md
│   └── tasks.md
├── index/
│   ├── items.json
│   └── topics.json
└── tool/
    ├── cli.php
    └── web/
        ├── git.index.php
        └── assets/
            ├── app.js
            └── style.css
```

## Data model

Each entry in `index/items.json` has:

- `id`: stable unique key, used by the CLI and web anchor links.
- `type`: `faq`, `task`, `cheat`, `glossary`, or `tutorial`.
- `topic`: a key defined in `topics.json`.
- `title`: short display title.
- `question`: optional user-style question.
- `tags`: search keywords.
- `content_md`: Markdown answer/body.
- `source`: originating document name.

`topics.json` defines display labels, descriptions, and display order.

## Web behavior

- The PHP page loads JSON from `../../index/` using paths relative to its own directory.
- Each item is rendered as a native HTML `<details>` element, which gives accessible individual toggles without JavaScript.
- “Expand all” and “Collapse all” set the `open` property of all matching `<details>` items.
- Search is performed client-side against normalized title, question, tags, source, and rendered text.
- The topic and type selectors are combined with the full-text filter.
- The URL can link directly to an item with `#item-id`.

## CLI behavior

```bash
php tool/cli.php help
php tool/cli.php topics
php tool/cli.php list
php tool/cli.php list --topic=versions
php tool/cli.php search "remote ssh"
php tool/cli.php show faq_tags
```

The CLI emits Markdown content. Use a pager only if you want one:

```bash
php tool/cli.php show faq_tags | less
```

## Installation

1. Unzip the bundle.
2. Put it anywhere readable by PHP.
3. CLI: run `php tool/cli.php help` from the bundle root.
4. Web: configure the web server document root or alias to `tool/web/`, then visit `git.index.php`.

For a quick local PHP test server from the bundle root:

```bash
php -S 127.0.0.1:8080 -t tool/web
```

Then visit:

```text
http://127.0.0.1:8080/git.index.php
```

## Maintenance

- Add or edit documentation in `docs/`.
- Add a corresponding item to `index/items.json`.
- Keep IDs stable once links have been shared.
- Use concise titles and several tags so searches are useful.
- This starter data is intentionally organized around your Git setup: macOS/Linux working copies, a Linux bare repository, SSH port 2222, version tags, and `VERSION`.