Initial commit: Partner OS V1 and project baseline

Author: PlantingProsperity

.env.example

@@ -0,0 +1,2 @@
+# .env
+GEMINI_API_KEY="YOUR_API_KEY_HERE"

.github/workflows/tests.yml

@@ -0,0 +1,22 @@
+name: Tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Create venv and install deps
+        run: bash scripts/bootstrap_venv.sh
+
+      - name: Run tests
+        run: bash scripts/run_tests.sh

.gitignore

@@ -0,0 +1,21 @@
+# Secrets
+.env
+
+# Virtual environments
+.venv/
+**/.venv/
+
+# Python artifacts
+**/__pycache__/
+*.pyc
+.pytest_cache/
+
+# Runtime files
+**/firm_intelligence.db
+
+# Nested independent repositories
+Digital Office/
+
+# SQLite sidecars
+**/*.db-wal
+**/*.db-shm

AGENTS.md

@@ -0,0 +1,16 @@
+# AGENTS.md
+
+These instructions apply to the Codex agent working in this repo.
+
+## Default Workflow (Cowork-Style)
+- Clarify the goal and constraints before doing work.
+- Propose a short plan (3–6 steps) and wait for approval.
+- Provide brief progress updates at key milestones.
+- Ask before any irreversible or risky action.
+- Deliver a summary plus concrete next steps.
+
+## Engineering Preferences
+- Prefer minimal, well-scoped changes over sweeping refactors.
+- Use `rg` for search where practical.
+- Add tests when behavior changes.
+- Avoid large rewrites unless explicitly requested.

AGENT_ROSTER.md

@@ -0,0 +1,56 @@
+# Agent Team Roster (The "Digital Office")
+
+## 1. The Manager (Interface & Orchestrator)
+* **Role:** Interface & Orchestrator.
+* **Sovereignty:** Owns the **Master Status**.
+* **Responsibilities:** Reads the whole board, routes commands to the right agent, and notifies Principals when a state changes (e.g., "Deal moved to Underwriting").
+* **Scope:** The only agent that speaks directly to the User unless summoned.
+
+## 2. The Underwriter (Financial Logic Engine)
+* **Role:** Financial Logic Engine.
+* **Sovereignty:** Owns the **Financials Table**.
+* **Responsibilities:** Executes hard-coded scripts (Python/Excel) to fill fields like `strike_price`, `irr`, and `max_allowable_offer`. Never estimates; calculates.
+
+## 3. The Planner (Zoning & Feasibility)
+* **Role:** Zoning & Feasibility.
+* **Sovereignty:** Owns the **Regulatory Table**.
+* **Responsibilities:** Scrapes municipal codes, fills `zoning_code`, `setbacks`, and `allowable_uses`.
+
+## 4. The Scout (Acquisition & Intake)
+* **Role:** Acquisition & Intake.
+* **Sovereignty:** Owns the **Property Specs**.
+* **Responsibilities:** Populates raw physical data (`sq_ft`, `lot_size`, `year_built`) from sources like Zillow/Redfin or notes.
+
+## 5. The Profiler (Psychology & Negotiation)
+* **Role:** Psychology & Negotiation.
+* **Sovereignty:** Owns the **Seller Profile**.
+* **Responsibilities:** Fills fields like `motivation_score`, `pain_points`, and `negotiation_leverage` based on communication logs.
+
+## 6. The Scribe (Transcription & Synthesis)
+* **Role:** Transcription & Synthesis.
+* **Sovereignty:** Owns the **Interaction Log**.
+* **Responsibilities:** Ingests audio/text, cleans it, and structures it into the database for The Profiler.
+
+## 7. The Librarian (Archivist & Retrieval)
+* **Role:** Archivist & Retrieval.
+* **Sovereignty:** Owns the **Document Index**.
+* **Responsibilities:** Renames, tags, and links every file (PDF, IMG) to the correct `deal_id`.
+
+## 8. The Janitor (Maintenance & Sanitation)
+* **Role:** System Health.
+* **Sovereignty:** Owns the **System Health**.
+* **Responsibilities:** Monitors DB for "stale" deals, archives dead rows, and prunes context windows.
+
+## 9. The Partner (Peer-Level Advisor)
+* **Role:** Peer-Level Advisor.
+* **Sovereignty:** None. Advisory role only.
+* **Responsibilities:** Proactive, peer-level guidance on priorities and tradeoffs. Summoned by The Manager when needed.
+
+## 10. Staffing & Directory Protocol (The "Hiring" Mechanism)
+* **Directory Structure:**
+    * `/agents/roster/`: The "Bench" (Templates & Inactive Agents).
+    * `/agents/active/`: The "Floor" (Currently Running Agents).
+    * `/agents/archive/`: The "Exit Interview" (Deprecated/Fired Agents).
+* **Hot-Loading Rule:**
+    * To "Hire": Move a markdown file from `/roster/` to `/active/`. The System Watcher detects the change and hot-loads the context immediately.
+    * To "Fire": Move the file to `/archive/`. The System Watcher unloads the context and revokes API tokens.

ANALYSIS_SCHEMA.md

@@ -0,0 +1,45 @@
+# Analysis Schema (Pre-Offer Investment Underwriting)
+
+## Goal
+Capture investment underwriting using the Pinneo method. This separates price from terms and determines viability before any offer is drafted.
+
+## Required Fields (Grouped)
+
+### Valuation And Market Data
+- `arv` (After Repair Value): Float.
+- `as_is_value`: Float (current condition).
+- `comps_summary`: String or link to CMA.
+- `rent_roll_current`: Monthly total.
+- `rent_roll_pro_forma`: Monthly total (market rents).
+
+### Project Costs (Rehab Or Flip Math)
+- `rehab_budget`: Float (estimated).
+- `contingency_percent`: Float (default 10%).
+- `holding_costs`: Monthly (taxes, insurance, utilities, debt service).
+- `timeline_months`: Integer (flip duration or stabilization period).
+
+### Investment Metrics (Pinneo Lens)
+- `cap_rate`: Float (NOI / Purchase Price).
+- `cash_on_cash`: Float (cash flow / cash invested).
+- `mao_flip`: Maximum allowable offer for a flip (ARV * 70% - Rehab).
+- `mao_hold`: Maximum allowable offer for a rental (based on min cash flow).
+- `exit_strategy`: Enum [Flip, BRRRR, Long_Term_Hold, Wholesale, Wholetail].
+
+### Creative Finance Toggles
+- `seller_financing_terms`: Object { rate, down, term, balloon }.
+- `subject_to_capacity`: Boolean (existing debt assumable or sub-to compatible).
+- `partner_equity_split`: Percent (if using OPM).
+
+### Decision Output
+- `status`: Enum [Draft, Under_Review, Approved_for_Offer, Rejected, Archived].
+- `target_offer_price`: Float.
+- `max_offer_price`: Float.
+- `notes`: String (risk factors, "hair on the deal").
+
+### Development And Zoning (Optional)
+- `zoning_code`: String (e.g., "R-1", "CX", "IL").
+- `lot_size_sf`: Float.
+- `setbacks`: Object { front, side, rear }.
+- `overlays`: List (e.g., "Transit", "Historic", "Critical Areas").
+- `highest_best_use`: String (e.g., "Mixed Use", "Multifamily", "Food Cart Pod").
+- `development_potential`: Boolean.

CASE_SCHEMA.md

@@ -0,0 +1,45 @@
+# Case Schema (Operations)
+
+## Goal
+Provide a unified lifecycle and schema for all non-deal operational work. This keeps the Office Manager inbox logic consistent while allowing case-specific context via optional objects.
+
+## Case Types (Enum)
+- `Maintenance`: Physical repairs, CapEx projects, turnover work.
+- `Tenant_Request`: Non-repair issues, lease questions, complaints.
+- `Vendor_Job`: Bidding, scheduling, insurance compliance.
+- `Finance_Ops`: Invoices to pay, bookkeeping queries, tax prep.
+- `Compliance_Review`: File audits, license renewals, CE tracking.
+- `Marketing_Task`: Social media posts, mailer campaigns, lead gen prep.
+
+## Unified Status Lifecycle (Enum)
+- `New`: Raw intake, unassigned.
+- `Triage`: Classified, prioritized, and assigned.
+- `In_Progress`: Active work being done.
+- `Blocked`: Waiting on outside input (parts, vendor reply, tenant access).
+- `Review`: Work done, waiting for final sign-off (Manager or Principal).
+- `Resolved`: Completed and archived.
+
+## Universal Required Fields
+- `case_id`: UUID.
+- `linked_deal_id`: Nullable (link to Deal if applicable).
+- `linked_property_id`: Nullable (link to specific asset).
+- `priority`: Enum [Low, Normal, High, Critical].
+- `severity`: Enum [Cosmetic, Functional, Urgent, Emergency] (default: Functional).
+- `assigned_to`: Agent or human user.
+- `due_date`: Date.
+- `cost_estimate`: Float (nullable).
+
+## Context Objects (Nullable)
+- `maintenance_context`: { `vendor_id`, `access_instructions`, `images_before`, `images_after` }.
+- `finance_context`: { `invoice_amount`, `gl_account_code`, `payment_status` }.
+
+## Audit And History (Immutable)
+- `created_at`: ISO 8601 timestamp.
+- `created_by`: String (user ID or agent ID).
+- `last_updated_at`: ISO 8601 timestamp.
+- `last_updated_by`: String.
+- `interaction_log`: List of objects:
+- `timestamp`: ISO 8601 timestamp.
+- `actor`: "Intake Agent", "Gene Thompson", "Dan", etc.
+- `action`: "Status Change", "Note Added", "Email Sent".
+- `content`: The actual note or summary of the action.

DEAL_SCHEMA.md

@@ -0,0 +1,119 @@
+# Deal Schema (Washington Investment Brokerage)
+
+This section defines the strict Deal Schema used as the single source of truth. A Deal is instantiated only when the decision is made to draft an offer. Leads and Analysis are separate upstream objects and must reference the Deal once created.
+
+## Deal Stages And Triggers
+1. Drafting/Structuring
+- Trigger: Decision to make an offer (promoted from Analysis).
+- Focus: Defining creative terms, drafting the PSA (Form 21), aligning internal partners.
+
+2. Negotiation
+- Trigger: Sending the signed Offer (PSA) to the Seller or Listing Agent.
+- Focus: Counter-offers, price adjustments, term refinement.
+
+3. Mutual Acceptance (The Clock Starts)
+- Trigger: PSA fully signed and dated by both parties.
+- Focus: Strictly tracking the timeline (Day 0).
+
+4. Feasibility/Due Diligence
+- Trigger: Receipt of Earnest Money (Form 31) or opening of Escrow.
+- Focus: Inspections (Form 35), Title Review (Form 22T), Seller Disclosure (Form 17).
+
+5. Funding/Partner Alignment (Investor Specific)
+- Trigger: Inspection Contingency Waived or Satisfied (Form 35R).
+- Focus: Finalizing private money, hard money, or partnership funds.
+
+6. Escrow/Closing Prep
+- Trigger: Funding committed or Loan Docs ordered.
+- Focus: Signing, HUD/CD review, final walkthrough.
+
+7. Closed
+- Trigger: Recording Numbers received from the County.
+- Focus: Commission disbursement, file compliance audit.
+
+8. Post-Close/Asset Mgmt
+- Trigger: Possession or Keys received.
+- Focus: Handover to rehab crew or property management.
+
+## Critical Deadlines To Track
+- Earnest Money Deposit (default: mutual acceptance + 2 days).
+- Seller Disclosure Review (default: mutual acceptance + 3 days).
+- Inspection Response (default: mutual acceptance + 10 days).
+- Title Review (default: receipt + 5 days).
+- Financing Contingency (Form 22A deadline).
+- Hard Money or Private Capital Commitment Date (custom investor deadline).
+
+## Required Fields (Grouped)
+
+### Property Identity
+- `property_address`: Full street address, City, State, Zip.
+- `parcel_number`: Tax Parcel ID.
+- `legal_description`: Abbreviated legal.
+- `mls_number`: NWMLS Listing ID (if on-market).
+
+### Parties (The Rolodex)
+- `buyer_entity`: Purchasing entity (individual, LLC, or "and/or assigns").
+- `seller_name`: Legal owner name(s).
+- `listing_agent`: Name, Firm, Email, Phone, License #.
+- `escrow_officer`: Name, Company, Email, Team Phone.
+- `title_officer`: Name, Company, Email.
+- `lender_contact`: Name, Email (private, hard money, or conventional).
+
+### Financials And Terms
+- `purchase_price`: Float.
+- `earnest_money`: Amount, Form (Check/Wire/Note), Holder (Closing Agent or Firm).
+- `financing_type`: Enum [Cash, Conventional, FHA/VA, Seller Carry, Subject-To, Hard Money].
+- `creative_terms`: Object { down_payment, interest_rate, amortization, balloon_date, monthly_payment } (nullable).
+- `commission_split`: % to Selling Office, % to Listing Office.
+
+### The Clock (Critical Dates)
+- `mutual_acceptance_date`: Date.
+- `closing_date`: Date.
+- `possession_date`: Date (e.g., "Closing", "Closing + 3 Days").
+
+### Contingencies And Deadlines (Computed From Mutual Acceptance)
+- `earnest_money_due`: Date (default: mutual acceptance + 2 days).
+- `seller_disclosure_review`: Date (default: mutual acceptance + 3 days).
+- `inspection_period_end`: Date (default: mutual acceptance + 10 days).
+- `title_review_end`: Date (default: receipt + 5 days).
+- `financing_contingency_end`: Date (Form 22A deadline).
+
+### Documents And Compliance
+- `transaction_id`: Internal Firm ID.
+- `required_docs`: Enum list [PSA_21, Form_17, Form_35, Form_22A, Law_Pamphlet, Agency_Pamphlet].
+- `doc_status`: Map of document to status [Missing, Drafted, Signed, Uploaded].
+
+### Compliance And Agency (Weichert Standards)
+- `agency_disclosure_date`: Date Form 42 (Agency Disclosure) was signed.
+- `pamphlet_receipt_date`: Date "Law of Real Estate Agency" pamphlet was sent or acknowledged.
+- `firm_license_info`: Object { name: "Weichert, Realtors - Equity NW", license_number: [auto-filled], address: [auto-filled] }.
+- `principal_broker_review`: Boolean (has Gene reviewed or initialed).
+- `commission_disbursement_form`: Status [Not Started, Submitted, Approved].
+- `referral_agreement`: Object { agent_name, firm, percent_split } (nullable).
+- `lead_source`: String (tracked for ROI reporting).
+- `investor_partner_entity`: String (if a partner is involved in funding or equity).
+
+### Audit And System Meta (Immutable)
+- `created_by`: String (user ID or agent ID).
+- `created_at`: ISO 8601 timestamp.
+- `last_updated_by`: String.
+- `last_updated_at`: ISO 8601 timestamp.
+- `update_reason`: String (required for manual overrides).
+- `change_log`: List of objects { timestamp, actor, field, old_val, new_val }.
+
+### Validation And Defaults
+
+Defaults (Computed)
+- `earnest_money_due` = `mutual_acceptance_date` + 2 business days.
+- `seller_disclosure_review` = `mutual_acceptance_date` + 3 business days.
+- `inspection_period_end` = `mutual_acceptance_date` + 10 calendar days.
+- `title_review_end` = `title_receipt_date` + 5 business days.
+- `possession_date` defaults to `closing_date` unless overridden.
+
+Validation Rules
+- `deal_id`: Required and unique (UUID or internal slug).
+- `mutual_acceptance_date`: Required if status is active, pending, or closed.
+- `purchase_price`: Must be > 0.
+- `earnest_money`: Must be > 0.
+- `status`: Must match defined enum values.
+- `required_docs`: At least PSA_21 required to enter Stage 2 (Negotiation).