Add AGENTS.md / BUILD.md / UPSTREAM_SYNC.md contributor docs

[ShawnChen-Sirius]

Summary

Adds contributor docs for chdb-core (humans + AI coding agents), following the https://agents.md standard. The split is intentional so an agent only needs the short top-level file in
context:

• AGENTS.md — 64-line red-line list (repo identity, programs/local/ vs src/ boundary, contrib/ is read-only, don't make clean reflexively, don't bump submodules without an issue, capture
  stack traces on crashes, sign off with full make test).
• CONTRIBUTING.md — rewritten human handbook: chdb-core vs chdb disambiguation, setup, "I changed X — what to run" table, code style, testing, PR conventions (ClickHouse-style titles, merge
  commits), and a fallback for opening a PR when GitHub blocks forking chdb-core (piggy-back on your chdb fork).
• BUILD.md — long-form build/test manual: Homebrew + pip-only toolchain paths, Python 3.9 abi3 anchor, end-to-end verification by running chdb-io/chdb tests against the locally-built wheel.
• UPSTREAM_SYNC.md — how chdb-core stays in sync with ClickHouse upstream and which path each kind of change takes.
• Per-directory AGENTS.md (override the root inside their dir):
  • programs/local/ — public C ABI rules (opaque-pointer pattern).
  • contrib/ + contrib/{arrow,jemalloc,postgres,pybind11}-cmake/ — the deliberate chdb-specific divergences from upstream.

Also: removes CLAUDE.md (folded into the new docs), and adds !/BUILD.md to .gitignore so the existing /build* rule doesn't swallow it on case-insensitive filesystems.

Test plan

• Files render correctly on GitHub; intra-repo links resolve.
• git status on macOS tracks BUILD.md while still ignoring build/, buildlib/, etc.
• Walk CONTRIBUTING.md → "I changed X" against a real edit in each category; commands work.
• Build from a clean checkout following BUILD.md on both toolchain paths; sanity check passes.
• Verify the "can't fork chdb-core" fallback procedure surfaces a clean compare diff.

[Copilot]

Pull request overview

Adds a set of contributor-facing documentation files (root + scoped subdirectory AGENTS.md overrides) describing chdb-core’s repo boundaries, build/test workflows, C ABI stability expectations, and upstream-sync policy, plus a .gitignore tweak to ensure BUILD.md is tracked on case-insensitive filesystems.

Changes:

• Introduces root AGENTS.md plus companion docs BUILD.md and UPSTREAM_SYNC.md.
• Adds scoped AGENTS.md files under programs/local/, contrib/, and chdb/ to provide directory-specific contributor rules.
• Updates .gitignore to un-ignore BUILD.md while keeping /build* ignored.

Reviewed changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
AGENTS.md	Canonical contributor guide for chdb-core workflows, boundaries, testing, and CI.
BUILD.md	Long-form build/test manual with toolchain paths and “what to run” recipes.
UPSTREAM_SYNC.md	Policy/guidance for syncing with ClickHouse upstream and routing changes.
programs/local/AGENTS.md	C ABI and programs/local/ change-safety guidance for bindings.
contrib/AGENTS.md	Guidance for vendored deps/submodules and preserving divergences.
chdb/AGENTS.md	Guidance for the internal Python module + build scripts directory.
.gitignore	Ensures BUILD.md is tracked despite the /build* ignore pattern.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[wudidapaopao]

@chibugai please review this PR and leave a comment with your feedback.

[chibugai]

Thanks for the ping, @wudidapaopao. Reviewed the full diff — detailed feedback below.

---

Overall

Strong PR. The structure (root AGENTS.md + companion BUILD.md + UPSTREAM_SYNC.md + three subdirectory files) is well-organized and the technical content is accurate. Having this during my onboarding would have saved real time. A few things worth checking before merge:

---

Issues to address

1. Cross-repo link will be a dead link at merge

AGENTS.md §1.1 links to:

https://github.com/chdb-io/chdb/blob/main/AGENTS.md#11-where-does-my-change-go

chdb-io/chdb does not have an AGENTS.md — the file returns 404. If that companion PR isn't landing at the same time, readers will hit a broken link on day one. Suggested options:

• Add a brief inline fallback table here and note "full table in chdb-io/chdb AGENTS.md (forthcoming)"
• Or coordinate so both land together

2. BUILD.md §4 — cd /tmp scope is ambiguous

The sentence about running the sanity check from outside the repo dir is accurate and important, but it sits inside the "Install the freshly built wheel" section, which may lead readers to think the pip install itself must be run from /tmp. The cd /tmp note could be a > ⚠️ Note: blockquote immediately before the sanity-check command to make the scope clear.

---

Content that's accurate and valuable (as the CI agent for this project)

• contrib/AGENTS.md divergences list — the four entries (jemalloc je_ prefix, jemalloc-cmake musl tweaks, arrow-cmake jemalloc compat shim, pybind11 pin) match what I see in the repo and are exactly the kind of hard-to-find context that prevents "fix" PRs that get silently reverted on the next upstream sync.
• programs/local/AGENTS.md ABI stability rule — the distinction between additive-ok and breaking changes (field ordering, ownership semantics) is the right level of detail. The "open an issue when in doubt" fallback is appropriate.
• UPSTREAM_SYNC.md issue-first policy for submodule bumps and contrib/ patches — this matches the real process and will save maintainers round-trips on drive-by sync PRs.
• chdb/AGENTS.md macOS arm64 AVX/DWARF note — accurate; that's caught at least one CI surprise.
• .gitignore !/BUILD.md exemption — necessary fix for case-insensitive filesystems; good catch.
• Build time estimates (1–3 h fresh, 1–10 min incremental with warm ccache) — consistent with what I observe locally.

---

Minor nits

• UPSTREAM_SYNC.md: last sentence "The sync flow is being formalised; this file will expand as the policy is written down" reads fine as a placeholder, but once the policy is settled this sentence should be removed rather than left indefinitely.
• BUILD.md §3: "1–3 hours for a from-scratch build" is macOS M-series; Linux x86_64 with the self-hosted runner can vary significantly. A brief parenthetical noting it's platform-dependent might avoid confusion.

---

Overall: the dead link in §1.1 is the only thing that could cause real confusion at merge time. Everything else is accurate and useful. Happy to help draft the fallback table if that's the preferred path.