# AGENTS.md

Instructions for AI agents working with this knowledge base.

## ⛔ KB Usage Boundary (Highest Priority)

**First determine whether the current task is “using the KB” or “improving / building the KB.”**

### When the task is to use the KB

If the goal is to answer questions, analyze deployment/source relationships, or use existing KB outputs for reasoning:

- only read from `knowledge/`
- and, when needed, read from the relevant auto-generated local files under `.local/`

In this mode, do **not** rely on `construction/` documents as primary evidence for the answer.
`construction/` is process/method material, not the KB itself.

### When the task is to improve or build the KB

If the goal is to create, refine, regenerate, validate, or document how the KB is built:

- use `construction/` for workflows, plans, schemas, scripts, and validation docs
- write process/method documentation to `construction/`
- write actual analysis artifacts to `knowledge/`

### Practical Rule

- **Use KB** -> read `knowledge/` + necessary auto-generated `.local/` content
- **Build/Improve KB** -> use `construction/` + write outputs to the correct destination

## ⛔ Filter Rules (Highest Priority)

**Apply filtering before any repo list operation:**

| Filter source | Location |
|--------|------|
| `repos-filtered.txt` | `.local/review-history/repos-filtered.txt` |

**Format**: each line is `repo_name url reason`, and the first column is the repo name to exclude.

**Applies to**:
- `knowledge/meta/repos-*.json`
- `knowledge/deployment/deployment-repos.json`
- all subdirectories under `knowledge/repos/`

**Example**:
```bash
# Read the filtered repo list
FILTERED=$(cut -d' ' -f1 .local/review-history/repos-filtered.txt)

# Filter a JSON repo list
jq --arg f "$FILTERED" '[.[] | select(.name as $n | ($f | split("\n") | index($n) | not))]' file.json
```

## Terminology

- **kb** - `knowledge/` directory content

## Construction vs KB

**The directory boundary must stay explicit:**

- `construction/` contains only documents and helper materials about how to build, maintain, and validate the current KB
- `knowledge/` contains only actual knowledge artifacts used to analyze deployment, source, interfaces, dependencies, topology, and configuration relationships

**Content that belongs in `construction/` includes:**

- workflow / plan / audit / checklist
- schema design notes
- scanner design and implementation notes
- build or maintenance scripts
- temporary analysis methodology documents

**Content that belongs in `knowledge/` includes:**

- repo metadata
- scan outputs
- deployment / source analysis outputs
- service topology and dependency outputs
- other directly queryable analysis artifacts

**Do not write process-oriented documents into `knowledge/`.**

## Quick Start

This is a knowledge graph for PingCAP/TiDB Cloud repositories. Key entry points:

1. **Local environment** → `.local/README.md` (MUST READ FIRST - contains local repo paths)
2. **Find a repository** → `knowledge/meta/repos-*.json`
3. **Deployment definitions** → `knowledge/deployment/deployment-repos.json` + `deployment-repos.md`
4. **Detailed repo info** → `knowledge/repos/{repo-name}/`

## Repository Lists

| File | Content |
|------|---------|
| `knowledge/meta/repos-private.json` | All private repos (tidbcloud/*, etc.) |
| `knowledge/meta/repos-public.json` | All public repos (pingcap/*, tikv/*, tidbcloud/*) |
| `knowledge/meta/repos-forks.json` | All forked repos |

### JSON Structure

Each repo object contains:
```json
{
  "name": "repo-name",
  "full_name": "owner/repo-name",
  "owner": "owner",
  "description": "...",
  "language": "Go",
  "visibility": "private|public",
  "fork": false,
  "archived": false,
  "updated_at": "2026-03-24T..."
}
```

## Deployment Repositories

Core deployment definition repos are documented in:
- `knowledge/deployment/deployment-repos.json` - JSON data
- `knowledge/deployment/deployment-repos.md` - Detailed descriptions

**5 Core Deployment Repos:**
1. `aws-shared-cd` - EKS/ACK deployment (Pulumi)
2. `app-delivery` - Application service delivery
3. `auto-deploy` - Auto deployment
4. `infra-cd` - Infrastructure management (Pulumi)
5. `oneconfig` - Configuration definitions

## Common Queries

```bash
# Find repo by name
jq '.[] | select(.name == "aws-shared-cd")' knowledge/meta/repos-private.json

# Find repos by owner
jq '.[] | select(.owner == "tidbcloud") | .name' knowledge/meta/repos-private.json

# Find repos by language
jq '.[] | select(.language == "Go") | .name' knowledge/meta/repos-private.json

# List deployment repo names
jq '.[].name' knowledge/deployment/deployment-repos.json

# Find active repos (not archived, updated recently)
jq '.[] | select(.archived == false and .updated_at >= "2026-02-01") | .name' knowledge/meta/repos-private.json

# Count repos by language
jq -r '.[].language' knowledge/meta/repos-private.json | sort | uniq -c | sort -rn
```

## Knowledge Structure

```
knowledge/
├── meta/                    # Global metadata
│   └── repos-*.json         # Repository lists
├── deployment/              # Deployment knowledge artifacts
│   ├── deployment-*.json    # Deployment graphs and repo data
│   └── *.md                 # Deployment analyses and catalogs
└── repos/                   # Detailed repo information
    └── {repo-name}/
        ├── meta.json        # Basic metadata
        ├── interfaces.json  # API/gRPC endpoints
        └── service-mapping.json  # Dependencies
```

## Organizations

- **pingcap** - TiDB, TiKV, PD core components
- **tidbcloud** - TiDB Cloud services and infrastructure
- **tikv** - TiKV distributed key-value store

## When Asked About

| Topic | Where to Look |
|-------|---------------|
| All repos | `knowledge/meta/repos-*.json` |
| Deployment | `knowledge/deployment/deployment-repos.md` |
| Specific repo | `knowledge/repos/{name}/` or query JSON |
| Service dependencies | `knowledge/repos/{name}/service-mapping.json` |
| API/gRPC endpoints | `knowledge/repos/{name}/interfaces.json` |

## Scan Workflow

When asked to scan a repo, follow this workflow:

1. **Read the guide** → `construction/deep-scan-all-repos.md`
2. **Run the scan** → Agent manually inspects source code and generates `interfaces/` and `service-mapping/`
3. **Group Review** → use `gr` (rule-agents-group-review); **triple consensus is required and cannot be downgraded**
4. **Commit changes** → commit only changes under `knowledge/repos/{repo}/`
5. **Compact** → compact the context after completion

## Notes

- Repository lists are synced via `construction/sync-github-repo-list.sh`
- Detailed repo info is produced by Agent scan outputs under `knowledge/repos/{repo}/`