docs: add github source of truth principle and update deep init (#585)

Author: sigvardt

AGENTS.md

@@ -1,5 +1,16 @@
 # AGENTS.md — Sub-Agent Instructions
 
+## Core Working Principle: GitHub Source of Truth
+
+**GitHub is our source of truth.** You have all history here. Use it when you're tackling a problem:
+- Search through previous issues.
+- Check commits and comments to understand what was tried before.
+- Maybe you've tried to fix this bug before.
+
+Always check the repository history before starting implementation.
+
+
+
 ## Repo Overview
 
 LinkedIn Buddy — Playwright-based browser automation for LinkedIn with CLI and MCP server.

packages/cli/src/AGENTS.md

@@ -3,7 +3,7 @@
 ## Overview
 
 Commander-based CLI exposing all core services as terminal commands. 127+ commands across 15 categories.
-Entry point: `bin/linkedin.ts` (11,100+ lines — largest file in the repo).
+Entry point: `bin/linkedin.ts` (14,077+ lines — largest file in the repo).
 
 ## Files
 
@@ -63,3 +63,8 @@ program
 - NEVER call core services without `try/finally` for `runtime.close()`
 - NEVER skip `--profile` option — every command needs profile selection
 - Output formatters belong in dedicated `*Output.ts` files, not inline in the command
+
+
+## Core Principle
+
+**GitHub is our source of truth.** Always check issue history, commits, and comments before starting implementation.

packages/core/src/AGENTS.md

@@ -7,17 +7,17 @@ Each follows the same pattern: TypeScript interfaces + service class + `prepare*
 
 | Module | Lines | Executors | Key Complexity |
 |--------|-------|-----------|----------------|
-| `linkedinProfile.ts` | 8,448 | 14 (intro, sections, photos, skills, etc.) | Largest service; multi-step profile editing |
-| `linkedinPosts.ts` | 5,216 | 3 (create, edit, delete) | Media handling, safety linting, async generators |
-| `linkedinInbox.ts` | 4,097 | 5 (send, react, archive, mute, add recipients) | Thread state management, SelectorCandidate pattern |
-| `linkedinFeed.ts` | 3,659 | 7 (like, comment, repost, share, save, unsave, remove) | Heavy selector fallback strategy |
-| `linkedinJobs.ts` | 3,102 | 4 (save, unsave, apply, alert) | Complex form filling for Easy Apply |
-| `linkedinPublishing.ts` | 2,676 | 2 (create article, publish newsletter) | Rich text composition |
-| `linkedinConnections.ts` | 2,406 | 8 (send, accept, withdraw, ignore, remove, follow, unfollow) | Full relationship lifecycle |
+| `linkedinProfile.ts` | 9,564 | 14 (intro, sections, photos, skills, etc.) | Largest service; multi-step profile editing |
+| `linkedinPosts.ts` | 5,905 | 3 (create, edit, delete) | Media handling, safety linting, async generators |
+| `linkedinInbox.ts` | 4,287 | 5 (send, react, archive, mute, add recipients) | Thread state management, SelectorCandidate pattern |
+| `linkedinFeed.ts` | 4,190 | 7 (like, comment, repost, share, save, unsave, remove) | Heavy selector fallback strategy |
+| `linkedinJobs.ts` | 3,821 | 4 (save, unsave, apply, alert) | Complex form filling for Easy Apply |
+| `linkedinPublishing.ts` | 2,977 | 2 (create article, publish newsletter) | Rich text composition |
+| `linkedinConnections.ts` | 2,780 | 8 (send, accept, withdraw, ignore, remove, follow, unfollow) | Full relationship lifecycle |
 
 ### Infrastructure
-- `runtime.ts` — Service graph factory (519 lines). **Central wiring point** — modify here to add services.
-- `twoPhaseCommit.ts` — Prepare/confirm framework (542 lines). Security-critical: token sealing, expiry, DB persistence.
+- `runtime.ts` — Service graph factory (546 lines). **Central wiring point** — modify here to add services.
+- `twoPhaseCommit.ts` — Prepare/confirm framework (685 lines). Security-critical: token sealing, expiry, DB persistence.
 - `config.ts` — Config resolution (1,297 lines, 53 exports). Paths, evasion, locale, privacy, webhooks.
 - `db/database.ts` — SQLite abstraction (2,615 lines, 50 exports). All persistent state lives here.
 - `rateLimiter.ts` — Token bucket. `peek()` for preview, `consume()` for enforcement.
@@ -29,7 +29,7 @@ Each follows the same pattern: TypeScript interfaces + service class + `prepare*
 - `linkedinPage.ts` — Page navigation, waiting strategies, selector helpers. Uses async generators.
 
 ### Humanization & Evasion
-- `humanize.ts` — Typing simulation (1,993 lines). Grapheme-level control, Intl.Segmenter for Unicode.
+- `humanize.ts` — Typing simulation (277 lines). Grapheme-level control, Intl.Segmenter for Unicode.
 - `evasion/` — Anti-bot subsystem (see `evasion/AGENTS.md`).
 
 ### Activity & Scheduling
@@ -58,3 +58,8 @@ Each follows the same pattern: TypeScript interfaces + service class + `prepare*
 - `SelectorCandidate[]` arrays: define in priority order (role → attribute → text → xpath)
 - All page interactions go through `humanize()` wrapper for typing, or `evasion` for mouse/scroll
 - DB queries use prepared statements — never raw string interpolation
+
+
+## Core Principle
+
+**GitHub is our source of truth.** Always check issue history, commits, and comments before starting implementation.

packages/core/src/__tests__/AGENTS.md

@@ -41,3 +41,8 @@ __tests__/
 - Mock the runtime object — never instantiate real services in unit tests
 - Use `vi.useFakeTimers()` for time-dependent tests (rate limiting, token expiry)
 - Test error paths: verify `LinkedInBuddyError` codes, not just "throws"
+
+
+## Core Principle
+
+**GitHub is our source of truth.** Always check issue history, commits, and comments before starting implementation.

packages/core/src/__tests__/e2e/AGENTS.md

@@ -80,3 +80,8 @@ Without these flags, write tests only execute prepare (no confirm).
 3. For read tests: call service methods, assert response structure
 4. For write tests: ONLY call `prepare*()` unless confirm opt-in flag is set
 5. Always clean up: close runtime in `afterAll()`
+
+
+## Core Principle
+
+**GitHub is our source of truth.** Always check issue history, commits, and comments before starting implementation.

packages/core/src/auth/AGENTS.md

@@ -9,6 +9,10 @@
 | `sessionInspection.ts` | Session diagnostics and health probes |
 | `loginSelectors.ts` | Login page selector strategies (email field, password field, submit button) |
 | `rateLimitState.ts` | Rate limit cooldown state — persisted to `rate-limit-state.json`, checked before operations |
+| `identityCache.ts` | Caches identity resolution results for sub-second identity checks |
+| `whoami.ts` | Fast identity extraction from cookies/DOM using cached hints |
+| `fingerprint.ts` | Browser fingerprinting utilities |
+| `sessionHealthCheck.ts` | Additional checks for session validity |
 
 ## Auth Flow
 
@@ -41,3 +45,8 @@ When LinkedIn returns HTTP 429/999 or a checkpoint URL:
 1. `rateLimitState.ts` records expiry timestamp
 2. All subsequent operations check cooldown before proceeding
 3. `keepAlive.ts` monitors and alerts on cooldown state
+
+
+## Core Principle
+
+**GitHub is our source of truth.** Always check issue history, commits, and comments before starting implementation.

packages/core/src/evasion/AGENTS.md

@@ -45,3 +45,8 @@ Diagnostics: set `LINKEDIN_BUDDY_EVASION_DIAGNOSTICS=true` for verbose logging.
 - NEVER make evasion patterns too uniform — randomization is critical for avoiding detection
 - NEVER skip evasion for credential entry — use `humanize.ts` typing profiles for sensitive fields
 - Changes to math distributions require careful validation — small changes can make patterns detectable
+
+
+## Core Principle
+
+**GitHub is our source of truth.** Always check issue history, commits, and comments before starting implementation.

packages/mcp/src/AGENTS.md

@@ -3,7 +3,7 @@
 ## Overview
 
 Model Context Protocol stdio server exposing all core services as AI-consumable tools.
-100+ tools across 15 categories. Entry point: `bin/linkedin-mcp.ts` (8,000+ lines).
+100+ tools across 15 categories. Entry point: `bin/linkedin-mcp.ts` (7,555+ lines).
 
 ## Files
 
@@ -87,3 +87,8 @@ async function handleToolName(args: ToolArgs): Promise<ToolResult> {
 - NEVER forget `runtime.close()` — always use try/finally
 - Tool names follow `linkedin.<domain>.<action>` convention — never deviate
 - All tools include optional `cdpUrl` and `selectorLocale` parameters
+
+
+## Core Principle
+
+**GitHub is our source of truth.** Always check issue history, commits, and comments before starting implementation.