AGENTS.md - Yanting Engineering Repo

Public agent instructions for this repository. This file is safe to commit. Local agents may read ignored AGENTS.local.md, but the repository must not depend on it. Last updated: 2026-06-03.

Project

This repository contains the Phase 1 implementation and engineering handoff for 研听 / report-notebooklm.

研听 is a Chinese research-report interpretation app. It turns global institutional research reports into structured Chinese reading and listening experiences. The product is an interpretation and annotation service, not investment advice.

Technical identifiers:

Code/API/internal name: report-notebooklm
Short prefix: rnb
API prefix: /api/report-notebooklm/v1
Database schema name: report_notebooklm
User-facing display name: 研听

Do not use the user-facing display name in code identifiers, database schema names, Redis keys, object-storage paths, or package names.

Repository Layout

This is intended to be a single Gitea repository.

Path	Purpose
`README.md`	Human-facing repository entry point.
`docs/`	Repo-level public handoff, decisions, and development history.
`report-notebooklm-api/`	FastAPI backend, database models, migrations, seed importer, API docs.
`report-notebooklm-app/`	Flutter app, Android/web scaffolds, App docs.
`docs.jimme.local/`	Ignored local-only notes, not required by the team.
`AGENTS.local.md`	Ignored local agent overlay.

Public vs Local Documentation

Public, committed documentation must be portable:

Use repository-relative paths.
Use environment variables and placeholders for credentials.
Describe product decisions in team-readable language.
Distinguish implemented behavior from planned/spec behavior.

Do not commit local-only material:

Local absolute paths.
Personal machine setup.
private agent workflow.
raw session logs.
local screenshots, APKs, caches, virtualenvs, build outputs.
credentials or local service passwords.

Use docs.jimme.local/ for ignored local notes and raw process references. Durable team-facing conclusions should be distilled into public docs/.

Product and Compliance Constraints

Public responses expose only reviewed display artifacts, not raw NotebookLM artifacts.
Public responses expose cache_version; display_version and module version are internal.
Do not expose raw artifact payloads, local file paths, NotebookLM notebook/source/conversation IDs, account identifiers, or private object-storage paths.
Phase 1 has no report-interpretation download feature.
Phase 1 does not include comments, UGC, paid unlocks, membership, task walls, points, trading signals, or investment recommendations.
NotebookLM-native/source-driven artifacts are the content source. Do not use local LLM rewriting to invent publishable report content.
Gray broker sources and generated media require compliance/operations review before public release.

Backend

Read first:

report-notebooklm-api/README.md
report-notebooklm-api/docs/HANDOFF.md
report-notebooklm-api/docs/API_AND_DATA.md
report-notebooklm-api/docs/CONTENT_PIPELINE.md
report-notebooklm-api/docs/RUNBOOK.md

Verify:

cd report-notebooklm-api
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
alembic upgrade head
python scripts/import_seed_content.py
pytest -q
uvicorn app.main:app --reload --host <bind-host> --port <port>

The backend requires .env settings for real MySQL/Redis environments. Use .env.example as the template. Do not commit .env.

App

Read first:

report-notebooklm-app/README.md
report-notebooklm-app/docs/HANDOFF.md
report-notebooklm-app/docs/API_CONTRACT_NOTES.md
report-notebooklm-app/docs/APP_RUNBOOK.md

Verify:

cd report-notebooklm-app
flutter analyze
flutter test
flutter build web --dart-define=RNB_API_BASE=<api-base-url>
flutter build apk --debug --dart-define=RNB_API_BASE=<emulator-api-base-url>

The App intentionally has no built-in live API default. Always pass RNB_API_BASE.

Decision Records

Long-lived decisions belong in docs/DECISIONS.md.

Development timeline and major implementation changes belong in docs/DEVELOPMENT_HISTORY.md.

Raw session logs, temporary planning transcripts, or local-only evidence pointers belong in ignored docs.jimme.local/.

Git Rules

Target remote: https://gitea.neuronlabs.art/third-party-project/yanting.git.
Commit one monorepo, not nested repositories.
Before the final monorepo push, remove or archive nested .git/ directories under subprojects so source files are committed as normal directories.
Keep .env, build artifacts, caches, APKs, local status files, and local agent overlays ignored.
Use English commit messages with prefixes such as feat:, fix:, docs:, and chore:.

4.8 KiB Raw Blame History