AGENTS.md git:20260329.5c9c21fA

Immutable. This exact content is served forever at /api/v1/blob/c2036b5ea05ec794.

# AGENTS.md

## Project Snapshot
- Repo: `jolestar/mdorigin`
- Main branch is the active integration branch.
- npm package has been released through GitHub Actions trusted publishing.
- Cloudflare site is deployed manually; merging to `main` does not deploy the site.

## Core Product Direction
- `mdorigin` is a programmable publishing core.
- The kernel owns routing, content-tree normalization, markdown/raw dual-view behavior, search integration, and other site semantics.
- Page rendering is extensible.
- Request/runtime internals are not intended to be replaced by user extensions.

## Important Implemented Features
- Raw markdown and HTML dual views.
- `Accept: text/markdown` content negotiation on extensionless routes.
- `README.md`, `index.md`, and `SKILL.md` directory entry support.
- Skill bundles are treated as post bundles by default.
- Symlinked content directories are supported in dev, `build index`, and Cloudflare bundle generation.
- Search is powered by `indexbind`.
- Code-based extension system exists via `mdorigin.config.ts`.

## Extension System
- Current stable hooks:
  - `transformIndex`
  - `renderHeader`
  - `renderFooter`
  - `renderPage`
  - `transformHtml`
- `defineConfig` is exported from the package root.
- See docs:
  - `docs/site/guides/extensions.md`
  - `docs/site/reference/configuration.md`

## Search Notes
- Search API:
  - `/api/search`
  - `/api/openapi.json`
- Search UI is already integrated into the site.
- Search uses `indexbind@0.2.1`.
- Default embedding backend is `model2vec`.
- Site-side reranking exists in `mdorigin`:
  - overview pages are lightly penalized
  - same-section results get soft diversity reranking
- Hybrid retrieval, if added later, should primarily live in `indexbind`, not `mdorigin`.

## Release Workflows
- CI workflow: `.github/workflows/ci.yml`
- Release workflow: `.github/workflows/release.yml`
- Trusted publishing is already configured and working.
- Typical release flow:
  1. `npm version patch -m "0.1.x"`
  2. `git push origin main`
  3. `git push origin v0.1.x`
  4. Verify GitHub Actions `Publish`
  5. Verify `npm view mdorigin version`

## Cloudflare Deployment
- Site URL: `https://mdorigin.jolestar.workers.dev`
- Deployment is manual.
- Use this sequence when site/runtime changes need deployment:

```bash
npm run build
npm run build:search -- --root docs/site --out dist/search
npm run build:cloudflare -- --root docs/site --out dist/cloudflare --search dist/search
npx wrangler deploy
```

- Important: deploying without a fresh `npm run build` may push an outdated runtime from `dist/`.

## Skills and Example Content
- `docs/site/skills` is a symlinked example skills section.
- `skills/mdorigin/SKILL.md` is the current mdorigin skill example.
- The skill intentionally stays concise and points agents to remote docs and `/api/search` for detail.

## Recent Known Good State
- npm version `0.1.8` was successfully released.
- Global CLI was updated and verified with `mdorigin --version`.
- Issue #10 was fixed in `0.1.8`:
  - managed index blocks now preserve explicit entry kind
  - catalog pagination correctly handles directory-based post bundles

## Recommended First Checks For New Agents
```bash
git status
git branch --show-current
mdorigin --version
npm view mdorigin version
```

## When Touching Site Output
- If a change affects rendered HTML, Cloudflare runtime, search runtime, or page footer/header behavior, rebuild before testing deployment.
- If a change lands in `main`, do not assume the public site is updated until `wrangler deploy` has been run.