docs: optimize canonical .md pack (CHITTY/CHARTER/SECURITY/AGENTS)#114
docs: optimize canonical .md pack (CHITTY/CHARTER/SECURITY/AGENTS)#114chitcommit merged 1 commit intomainfrom
Conversation
Sync the canonical documentation pack to reflect Phase 3.5/4/6 state and add AGENTS.md for agent registry discoverability. CHITTY.md: - type: summary → architecture (resolves open compliance follow-up) - Fill ChittyID (did:chitty:REG-XE6835) and registration date - Expand endpoint surface from 12 paths to 22 categories matching the 33 route modules in server/routes/ (properties, allocations, classification, COA, valuation, imports, forensics, ChittyID SSO, MCP, etc.) - Dependencies grew from 7 to 13 services, each marked Live / Partial / Pending; flag ChittyChronicle read-side as blocked, ChittyCert + MCP as Phase 5/2 pending CHARTER.md: - Scope updated to reflect shipped capabilities through Phase 6 (allocations, exports, classification trust-path, COA admin, valuation, CSV imports, Schedule E, forensics, inbound email) - API Contract: 12 → ~50 endpoints across 11 categories - Compliance checklist: 8 → 17 items (HMAC webhooks, classification trust path, ChittyID SSO PKCE, multi-currency, schema registration, discovery) - Dependencies marked Live / Partial / Pending - Last Updated: 2026-03-22 → 2026-05-02 SECURITY.md: - Mercury per-tenant HMAC-SHA256 webhook details (7 active registrations) - ChittyID OAuth 2.0 PKCE primary auth path - ChittyOS integrations table (auth direction per peer service) - npm audit alongside pnpm audit (both lock files present) - Bot detection + script injection prevention (PR #95 hardening) - Known Limitations: ChittyChronicle read-side blocked, ChittySchema fall-open, app-level rate limiting open AGENTS.md (new): - Internal AI agents: classification (GPT-4o-mini, L1), advice (GPT-4o), optimizer - MCP capabilities exposed under /api/mcp/* - ChittyOS agents that interact with this service - Dev subagent guidance (chittyschema-overlord, chittycanon-code-cardinal, chittyconnect-concierge, etc.) - Agent trust boundaries (what is and isn't delegated) - Contribution guide for new agent integrations Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Deploying with
|
| Status | Name | Latest Commit | Updated (UTC) |
|---|---|---|---|
| ❌ Deployment failed View logs |
chittyfinance | f1b2d61 | May 02 2026, 12:41 PM |
|
@coderabbitai review Please evaluate:
|
|
Caution Review failedPull request was closed or merged during review 📝 WalkthroughWalkthroughThis PR expands ChittyFinance's documentation across four key files to comprehensively define the system's architecture, capabilities, agent integration framework, API contracts, and security policies, moving from summary-level descriptions to detailed operational specifications. ChangesComprehensive System Documentation Update
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Review rate limit: 0/1 reviews remaining, refill in 60 minutes.Comment |
Code Review — PR #114: docs: optimize canonical .md packDocs-only PR. No runtime impact. The changes accurately reflect Phase 3.5/4/6 shipped state and the new AGENTS.md is a useful addition to the canonical pack. A few items worth flagging before merge: ✅ What's well done
|
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f1b2d61ce1
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | Mercury | `/api/mercury/{accounts,select-accounts}` | Hybrid | | ||
| | Webhooks | `/api/integrations/{stripe,mercury,wave}/webhook` | Signature-verified | | ||
| | Email | `/api/email/*`, inbound handler for `finance@chitty.cc` | Hybrid | | ||
| | MCP | `/api/mcp/*` | Bearer | |
There was a problem hiding this comment.
Update this endpoint to /mcp (not /api/mcp/*) so clients can connect successfully. The server only registers POST /mcp in server/routes/mcp.ts and protects /mcp in server/app.ts; publishing /api/mcp/* in the architecture doc will cause integrators to call a non-existent path and receive 404s.
Useful? React with 👍 / 👎.
| | `/api/classification/queue` | GET | Pending classification queue | | ||
| | `/api/classification/suggest` | POST | AI-suggest COA code (L1) | | ||
| | `/api/classification/classify` | POST | Set authoritative COA (L2) | | ||
| | `/api/classification/bulk-accept` | POST | Bulk-accept high-confidence (≥0.80, ≤$500) | | ||
| | `/api/chart-of-accounts` | GET/POST/PATCH | COA admin (L4 owner/admin only) | |
There was a problem hiding this comment.
These paths do not match the implemented API: there is no /api/classification/queue, /api/classification/bulk-accept, or /api/chart-of-accounts route in the server. The current implementation exposes /api/classification/unclassified plus /api/classification/{batch-suggest,ai-suggest} and COA routes under /api/coa (see server/routes/classification.ts), so the published contract currently directs clients to endpoints that fail.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Pull request overview
Updates the repo’s canonical documentation pack to reflect the current shipped state (Phase 3.5/4/6) and adds a new AGENTS.md registry document for agent discoverability across the ChittyOS ecosystem.
Changes:
- Updated
CHITTY.mdfrontmatter/type and refreshed architecture/dependencies + endpoint categorization. - Expanded
CHARTER.mdscope/dependencies and significantly updated the API contract + compliance checklist. - Refreshed
SECURITY.mdOAuth/webhook security details and added a ChittyOS integrations section; added newAGENTS.md.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 18 comments.
| File | Description |
|---|---|
| SECURITY.md | Updates OAuth/webhook security notes, integrations tables, CI/CD security notes, and known limitations. |
| CHITTY.md | Updates doc type to architecture; refreshes stack/dependencies and replaces endpoint list with categorized route summary. |
| CHARTER.md | Expands scope/dependencies and rewrites the API contract + compliance checklist to match current phases. |
| AGENTS.md | Adds a public agent registry covering internal AI agents, MCP surface area, and trust boundaries. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| | Leases | `/api/leases/expiring`, `/api/properties/:id/leases` | Hybrid | | ||
| | Allocations | `/api/allocations/{rules,preview,execute,runs}` | Hybrid | | ||
| | Classification | `/api/classification/{queue,suggest,classify,bulk-accept}` | Hybrid | | ||
| | COA Admin | `/api/chart-of-accounts` (L4 owner/admin) | Hybrid | |
| | Mercury | `/api/mercury/{accounts,select-accounts}` | Hybrid | | ||
| | Webhooks | `/api/integrations/{stripe,mercury,wave}/webhook` | Signature-verified | | ||
| | Email | `/api/email/*`, inbound handler for `finance@chitty.cc` | Hybrid | | ||
| | MCP | `/api/mcp/*` | Bearer | |
| ### Financial Advice (GPT-4o) | ||
| - **Source**: `server/lib/openai.ts` | ||
| - **Endpoints**: `/api/ai/advice`, `/api/ai/cost-reduction`, `/api/ai/message` | ||
| - **Max tokens**: 500 per request |
| 1. **Session auth is SHA-256, not PBKDF2/bcrypt** -- acceptable for Workers environment (no Node.js crypto), ChittyID SSO is the primary auth path | ||
| 2. **No request rate limiting** -- relies on Cloudflare's built-in DDoS protection | ||
| 3. **Forensic tables use integer IDs** -- legacy schema, not yet migrated to UUID | ||
| 1. **Legacy session auth uses SHA-256, not PBKDF2/bcrypt** — acceptable for Workers environment (no Node.js crypto); ChittyID SSO (OAuth 2.0 PKCE) is the primary auth path |
| | AI | `/api/ai/{advice,cost-reduction,message}` | Hybrid | | ||
| | Integrations | `/api/integrations`, `/api/integrations/status`, `/api/integrations/wave/{authorize,callback,refresh}`, `/api/integrations/stripe/{connect,checkout,webhook}` | Mixed | | ||
| | Mercury | `/api/mercury/{accounts,select-accounts}` | Hybrid | | ||
| | Webhooks | `/api/integrations/{stripe,mercury,wave}/webhook` | Signature-verified | |
| - **CodeQL**: Static analysis on every PR (27 alerts resolved 2026-03-24) | ||
| - **Secret scanning**: Working tree scanned for credential patterns | ||
| - **Dependency audit**: `pnpm audit --prod --audit-level high` | ||
| - **Dependency audit**: `npm audit --omit=dev --audit-level high` (or `pnpm audit` if using pnpm-lock) |
| |----------|--------|---------| | ||
| | `/api/integrations/status` | GET | Integration config status | | ||
| | `/api/integrations/wave/{authorize,callback,refresh}` | GET/POST | Wave OAuth flow | | ||
| | `/api/integrations/stripe/{connect,checkout,webhook}` | POST | Stripe customer + checkout + webhook | |
| | `/api/integrations/wave/{authorize,callback,refresh}` | GET/POST | Wave OAuth flow | | ||
| | `/api/integrations/stripe/{connect,checkout,webhook}` | POST | Stripe customer + checkout + webhook | | ||
| | `/api/mercury/{accounts,select-accounts}` | GET/POST | Mercury accounts via ChittyConnect | | ||
| | `/api/integrations/{mercury,wave}/webhook` | POST | Webhooks (per-tenant HMAC-SHA256) | |
| Mounted under `/api/mcp/*`. Resources include: | ||
| - Financial summaries (tenant-scoped) | ||
| - Transaction queries | ||
| - Property financials (NOI, cap rate, occupancy) | ||
| - Allocation rule preview | ||
| - Schedule E line summary | ||
|
|
||
| Authentication: Bearer service token. See [SECURITY.md](SECURITY.md). |
| - **Fallback**: Rule-based advice when `OPENAI_API_KEY` is unset | ||
|
|
||
| ### Recurring Charge Optimizer | ||
| - **Source**: `server/lib/chargeAutomation.ts` |
Summary
Sync the canonical documentation pack to reflect current Phase 3.5/4/6 shipped state and add
AGENTS.mdfor agent registry discoverability.type: summary→architecture(resolves open compliance follow-up); filldid:chitty:REG-XE6835; endpoint table modernized to 22 categories matching 33 route modules; deps grew 7 → 13 with Live/Partial/Pending statusTest plan
type: architecture(wassummary)server/app.tsroute mounts (verified against 33 modules inserver/routes/)Notes
stoppedfailure (issue Workers Builds: chittyfinance — instant 0s failure on every PR + main #111) — auto-merge configured to ignoreMEMORY.mdwas also trimmed in the same session (224 → 69 lines, content moved to topic files); that work stays in~/.claude/, not pushed🤖 Generated with Claude Code
Summary by CodeRabbit