# Top Rule: No Placeholders or Mock Data

- Use only actual values. Do not include sample, placeholder, or mock data in code, docs, examples, or commands.
- If a placeholder appears necessary, pause and request explicit approval and the real values before proceeding.
- Examples must avoid fake tokens/IDs. Reference variables conceptually without inserting dummy values.

# Project Copilot Instructions (Reusable, production-ready)

## Lessons Learned (Notes sync)
- Normalize Notes: convert `\r\n`→`\n`, trim both sides before compare/merge.
- Merge policy: if different, concatenate Excel and PB with a blank line; do not use substring containment to decide equality.
- Write Notes via table column `.../columns/Notes/dataBodyRange/cell(row=X,column=0)` to protect formula columns.
- Run a fresh audit before apply; avoid stale `applied_updates_deltas.json` or cached fetches.
- Poller must only update when `notesMergeNeeded` is true; otherwise skip to prevent touching every row.

## Core Policy
- Zero user interaction. Backends must run unattended.
- Tokens are delivered programmatically (env/API/CLI). No device-code or browser prompts.

## Auth & Tokens
- PocketBase: use agent/service account for system ops; user token only for attribution.
- Graph: prefer app-only (client credentials); delegated only if explicitly provided.
- Tokens stay in memory only; cache until expiry. Optional hint: `GRAPH_TOKEN_EXPIRES_AT` (unix ms); warn when <5 min.

## Excel + Graph
- Use table endpoints: `/workbook/tables/{name}/rows` and `/columns`; send `workbook-session-id`.
- Compute values server-side; column formula seeding is unreliable. For newest-first inserts use `index: 0`.

## Data Rules
- Primary key: `Job_Number` is immutable and required on every row (exact header match).
- Booleans: normalize common fields (`active`, `*_flag`, `is_*`, `tax_exempt`).
- Dates: store UTC ISO; display `MM/dd/yyyy` using UTC accessors; convert Excel serials to UTC.
- Case-insensitive column/field matching.

## Environment (baseline)
- PocketBase: `PB_DB` or `REDIRECT_URI`, `PB_COLLECTION`, `PB_AUTH_COLLECTION` (default `Users`), `PB_AGENT_EMAIL`, `PB_AGENT_PASSWORD`.
- Graph: `CLIENT_ID`, `TENANT_ID`; optional `GRAPH_USER_SCOPES`, optional delegated `GRAPH_ACCESS_TOKEN`.
- Excel: `DRIVE_ID`, `ITEM_ID`, `EXCEL_TABLE`.
- Poller: `POLL_INTERVAL_SEC`.
- Optional: `GRAPH_TOKEN_EXPIRES_AT` (unix ms).

## Logging
- Symbols: ✓ success, ✗ error, ⚠️ warning, ℹ️ info.
- Change log: `[timestamp] Job: # | PB ID: | Action: ADDED/UPDATED | Changes: field: "old" → "new"`.

## tsconfig.json template (Bun/TypeScript)
```jsonc
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "lib": ["ESNext"],
    "moduleResolution": "bundler",
    "skipLibCheck": true,
    "noImplicitAny": false,
    "allowJs": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "noEmit": true,
    "allowImportingTsExtensions": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}
```

## Bun/TypeScript hardening
- Bun fetch Response: use `(resp as any).ok|text|json|status`.
- Bun.serve Request: `fetch: async (req: any)` and `(req as any).method|url|json`.
- Bun types: add `src/bun.d.ts` stub declaring `Bun.serve` (no @types package needed).
- Deleted-file noise: ensure tsconfig include/exclude above; if VS Code persists, restart TS server.

## Adherence
- Assistant must respect this file at session start.
- Hide/skip login UI unless a delegated token is explicitly required and unavailable programmatically.

## Reference
- Org-wide standards: `global-copilot-instructions.md`.
