docs: Add complete NaviDocs handover documentation and StackCP analysis

This commit finalizes the NaviDocs MVP documentation with comprehensive handover materials. ## Documentation Added: 1. **NAVIDOCS_HANDOVER.md** - Complete project handover (65% MVP complete) - Executive summary and current status - Repository structure and component details - Testing results and known issues - Deployment options (StackCP vs VPS) - Next steps and risk assessment - Success metrics and recommendations 2. **StackCP Analysis Documents**: - ANALYSIS_INDEX.md - Master overview - STACKCP_ARCHITECTURE_ANALYSIS.md - Technical deep-dive - STACKCP_DEBATE_BRIEF.md - Deployment decision framework - STACKCP_QUICK_REFERENCE.md - Fast decision-making tool ## Current State Summary: **Completed** (65% MVP): - ✅ Database schema (13 tables, fully normalized) - ✅ OCR pipeline (3 options: Tesseract 85%, Google Drive, Google Vision) - ✅ Upload endpoint with background processing - ✅ StackCP deployment fully evaluated - ✅ Local development environment operational **Pending** (35% to MVP): - ⚠️ Meilisearch authentication (15-min fix) - ⚠️ Frontend UI incomplete (1-2 days) - ⚠️ Authentication not implemented (1 day) - ⚠️ Tests needed (2-3 days) ## Deployment Options: **StackCP Shared Hosting**: /bin/bash infrastructure, suitable for <5K docs/month **VPS Alternative**: /month, better for scale ## Key Findings: - Upload + OCR pipeline: ✅ Working (85% confidence) - Database: 184KB with test data - Services: Redis ✅, Meilisearch ⚠️ (auth issue), API ✅, Worker ✅ - Git: 18 commits, all code committed Ready for: Development continuation, deployment preparation Not ready for: Production (needs auth + testing) 🚀 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-19 13:19:42 +02:00 · 2025-10-19 13:19:42 +02:00 · eaf9fae275
commit eaf9fae275
parent 1d41677995
5 changed files with 3159 additions and 0 deletions
--- a/ANALYSIS_INDEX.md
+++ b/ANALYSIS_INDEX.md
@ -0,0 +1,290 @@
+# StackCP Architecture Analysis - Document Index
+
+**Analysis Date**: 2025-10-19
+**Tech Lead**: Autonomous Development Prompt Evaluation
+**Target**: StackCP (20i) Shared Hosting Deployment
+**Status**: Ready for technical debate
+
+---
+
+## Document Overview
+
+This analysis evaluates the FastFile/NaviDocs autonomous development prompt and deployment strategy against the discovered StackCP constraints. Three comprehensive documents have been prepared for the technical debate.
+
+---
+
+## Document 1: Comprehensive Analysis
+
+**File**: `/home/setup/navidocs/STACKCP_ARCHITECTURE_ANALYSIS.md`
+
+**Purpose**: Deep technical analysis of architectural impacts
+
+**Contents**:
+1. Executive Summary
+2. Critical Issues (Blockers)
+   - Repository structure assumptions
+   - Native module compilation
+   - Process management
+   - File persistence
+   - Development workflow
+3. Major Revisions Needed
+   - Mission statement
+   - Technology stack
+   - Deployment strategy
+   - Development workflow
+   - Backup/recovery
+4. Minor Tweaks (sections that mostly work)
+5. Proposed Repository Structure
+6. Revised Deployment Steps
+7. Path Configuration Strategy
+8. Operational Concerns
+9. Testing Strategy
+10. Implementation Priority
+11. Risks and Mitigations
+
+**Audience**: Technical implementers, architects
+**Reading Time**: 30-40 minutes
+**Use Case**: Detailed implementation planning
+
+---
+
+## Document 2: Debate Brief
+
+**File**: `/home/setup/navidocs/STACKCP_DEBATE_BRIEF.md`
+
+**Purpose**: Structure the technical debate with Security and OCI experts
+
+**Contents**:
+1. The Situation (constraints summary)
+2. Architectural Impact (code, ops, docs changes)
+3. Key Questions for Each Expert
+   - Security Expert: Risk assessment, external services, code integrity
+   - OCI Architect: Container alternatives, portability, operational complexity
+   - Tech Lead: Developer experience, testing, rollout plan
+4. Three Paths Forward
+   - Path A: Full StackCP adaptation (5-7 days)
+   - Path B: Hybrid approach (3-4 days)
+   - Path C: Abandon StackCP, use VPS (1 day)
+5. Cost Comparison (detailed analysis)
+6. Security Risk Matrix
+7. Technical Debt Analysis
+8. Recommendations
+9. Decision Framework
+10. Proposed Action Items
+
+**Audience**: Decision-makers, security experts, architects
+**Reading Time**: 20-30 minutes
+**Use Case**: Facilitate structured debate and decision
+
+---
+
+## Document 3: Quick Reference Card
+
+**File**: `/home/setup/navidocs/STACKCP_QUICK_REFERENCE.md`
+
+**Purpose**: Fast decision-making during debate
+
+**Contents**:
+1. Core Problem (visual diagram)
+2. Three Paths Decision Matrix
+3. Critical Architectural Changes (code examples)
+4. Security Risk Assessment (tables)
+5. Cost Analysis (real numbers)
+6. Decision Tree (flowchart)
+7. Key Questions (< 5 min to answer)
+8. Recommendation Algorithm
+9. What Changes in Each Path (checklist)
+10. Immediate Actions (next 60 minutes)
+11. Red Flags (abort criteria)
+12. Final Recommendation
+13. Debate Checklist
+
+**Audience**: All stakeholders during live debate
+**Reading Time**: 5-10 minutes
+**Use Case**: Quick reference, decision checklist
+
+---
+
+## Supporting Documents (Already Exist)
+
+### StackCP Evaluation Reports
+- `/home/setup/navidocs/STACKCP_EVALUATION_REPORT.md` - Initial evaluation (445 lines)
+- `/home/setup/navidocs/STACKCP_VERIFICATION_SUMMARY.md` - Test results (433 lines)
+- `/home/setup/navidocs/docs/DEPLOYMENT_STACKCP.md` - Original deployment guide (375 lines)
+- `/home/setup/navidocs/docs/STACKCP_QUICKSTART.md` - Quick start guide (301 lines)
+
+### NaviDocs Core Documentation
+- `/home/setup/navidocs/README.md` - Project overview
+- `/home/setup/navidocs/ARCHITECTURE-SUMMARY.md` - Architecture decisions
+- `/home/setup/navidocs/docs/roadmap/v1.0-mvp.md` - MVP roadmap
+- `/home/setup/navidocs/docs/roadmap/2-week-launch-plan.md` - Launch plan
+
+---
+
+## Key Findings Summary
+
+### Critical Discovery
+**Only `/tmp` has executable permissions** on StackCP shared hosting
+- Home directory is `noexec` (cannot run binaries or compile native modules)
+- Application code MUST be in `/tmp/navidocs/`
+- Data (database, uploads) MUST be in `~/navidocs/`
+- This fundamentally breaks standard deployment assumptions
+
+### Architectural Blockers
+1. **Repository structure**: Assumes single location for code + data
+2. **Native modules**: Cannot compile in home directory
+3. **Process management**: PM2/systemd assumptions may not work
+4. **File persistence**: `/tmp` may be cleared on reboot
+5. **Development workflow**: npm must be executed via wrapper
+
+### Required Changes
+1. **Code** (2-3 days): Path configuration, environment detection
+2. **Operations** (1-2 days): Checkpoint scripts, health checks, backups
+3. **Documentation** (1-2 days): Rewrite deployment guides
+4. **Testing** (1 day): StackCP-specific scenarios
+
+**Total**: 5-7 days for full StackCP adaptation
+
+### Alternatives
+1. **VPS Deployment** (1 day): Standard environment, $5-6/month
+2. **Container Platform** (1 day): Modern deployment, $5-10/month
+3. **Hybrid Approach** (3-4 days): Support both StackCP and standard
+
+---
+
+## Cost-Benefit Analysis
+
+### StackCP Adaptation
+- **Time**: 5-7 days development
+- **Cost**: $0 new (using existing hosting)
+- **Operational overhead**: Ongoing custom scripts
+- **Technical debt**: Medium-High (StackCP-specific code)
+- **Security risk**: Medium (code exposure in `/tmp`)
+
+### VPS Alternative
+- **Time**: 1 day development
+- **Cost**: $6/month ($72/year)
+- **Operational overhead**: Standard (PM2, systemd)
+- **Technical debt**: Low (industry standard)
+- **Security risk**: Low (standard practices)
+
+**Savings with VPS**: $2,400-4,100 in Year 1 (considering developer time)
+
+---
+
+## Recommended Decision Path
+
+### Step 1: Answer Key Questions (5 minutes)
+Use `/home/setup/navidocs/STACKCP_QUICK_REFERENCE.md` section "Key Questions"
+
+### Step 2: Evaluate Risks (10 minutes)
+Review security and operational risks in Debate Brief
+
+### Step 3: Choose Path (5 minutes)
+- **Path A**: Full StackCP (only if hard requirement + acceptable risks)
+- **Path B**: Hybrid (if learning value + time available)
+- **Path C**: VPS (default recommendation)
+
+### Step 4: Implement (1-7 days)
+Follow implementation plan in chosen path
+
+---
+
+## For Immediate Use
+
+### Starting the Debate
+1. **Open**: `STACKCP_QUICK_REFERENCE.md` (shared screen)
+2. **Reference**: `STACKCP_DEBATE_BRIEF.md` (for detailed questions)
+3. **Backup**: `STACKCP_ARCHITECTURE_ANALYSIS.md` (for technical details)
+
+### Decision Checklist
+- [ ] Why StackCP? (cost, existing account, learning)
+- [ ] Security acceptable? (code exposure, external services)
+- [ ] Timeline? (1 day VPS vs 5-7 days StackCP)
+- [ ] Long-term vision? (personal, startup, enterprise)
+- [ ] Maintenance capacity? (solo, team, DevOps)
+
+### After Decision
+- [ ] Document chosen path in project README
+- [ ] Update ARCHITECTURE-SUMMARY.md with constraints
+- [ ] Create implementation task list
+- [ ] Assign owner for implementation
+- [ ] Set review milestones
+
+---
+
+## File Locations Summary
+
+```
+/home/setup/navidocs/
+├── STACKCP_ARCHITECTURE_ANALYSIS.md   ← Full technical analysis (this evaluation)
+├── STACKCP_DEBATE_BRIEF.md            ← Structured debate guide
+├── STACKCP_QUICK_REFERENCE.md         ← Quick decision reference
+├── ANALYSIS_INDEX.md                  ← This file (overview)
+├── STACKCP_EVALUATION_REPORT.md       ← Initial evaluation (existing)
+├── STACKCP_VERIFICATION_SUMMARY.md    ← Test results (existing)
+├── README.md                          ← Project overview
+├── ARCHITECTURE-SUMMARY.md            ← Architecture decisions
+└── docs/
+    ├── DEPLOYMENT_STACKCP.md          ← Original deployment guide (needs revision)
+    ├── STACKCP_QUICKSTART.md          ← Quick start (needs revision)
+    └── roadmap/
+        ├── v1.0-mvp.md                ← MVP roadmap (needs revision)
+        └── 2-week-launch-plan.md      ← Launch plan (needs revision)
+```
+
+---
+
+## Next Actions
+
+### Before Debate
+- [ ] Review all three analysis documents
+- [ ] Prepare answers to "Key Questions" in Quick Reference
+- [ ] Gather stakeholders (Security, OCI, Tech Lead)
+- [ ] Allocate 30-60 minutes for debate
+
+### During Debate
+- [ ] Present findings (10 min)
+- [ ] Security expert review (10 min)
+- [ ] OCI architect review (10 min)
+- [ ] Cost-benefit discussion (10 min)
+- [ ] Decision vote (5 min)
+- [ ] Action item assignment (5 min)
+
+### After Debate
+- [ ] Document decision in project docs
+- [ ] Create implementation task list
+- [ ] Update autonomous development prompt (if needed)
+- [ ] Revise Mission statement (if StackCP chosen)
+- [ ] Begin implementation
+
+---
+
+## Contact Information
+
+**Analysis Prepared By**: Tech Lead (Claude Code)
+**Date**: 2025-10-19
+**Review Status**: Awaiting technical debate
+**Decision Deadline**: Before Phase 1 implementation
+
+---
+
+## Summary
+
+This analysis provides three comprehensive documents for evaluating NaviDocs deployment on StackCP:
+
+1. **STACKCP_ARCHITECTURE_ANALYSIS.md**: Complete technical breakdown
+2. **STACKCP_DEBATE_BRIEF.md**: Structured debate guide
+3. **STACKCP_QUICK_REFERENCE.md**: Fast decision-making tool
+
+**Recommendation**: Path C (VPS) for production, Path B (Hybrid) if StackCP required
+
+**Estimated Savings**: $2,400-4,100 Year 1 by choosing VPS over StackCP
+
+**Key Risk**: Code exposure in `/tmp` on StackCP shared hosting
+
+**Timeline**: 1 day (VPS) vs 5-7 days (StackCP adaptation)
+
+---
+
+**Ready for debate and decision.**
--- a/NAVIDOCS_HANDOVER.md
+++ b/NAVIDOCS_HANDOVER.md
--- a/STACKCP_ARCHITECTURE_ANALYSIS.md
+++ b/STACKCP_ARCHITECTURE_ANALYSIS.md
--- a/STACKCP_DEBATE_BRIEF.md
+++ b/STACKCP_DEBATE_BRIEF.md
@ -0,0 +1,397 @@
+# StackCP Deployment Debate Brief
+
+**For**: Security Expert, OCI Architect, Tech Lead Discussion
+**Subject**: NaviDocs Deployment on StackCP Shared Hosting
+**Date**: 2025-10-19
+**Status**: Awaiting technical consensus
+
+---
+
+## The Situation
+
+NaviDocs was designed with standard deployment assumptions (local services, normal filesystem permissions, VPS-like environment). Recent evaluation of StackCP (20i shared hosting) revealed **critical constraints** that break these assumptions.
+
+**Key Discovery**: Only `/tmp` directory has executable permissions; home directory is mounted `noexec`.
+
+---
+
+## Critical Constraints Summary
+
+### 1. File System Constraints
+- **Executable location**: ONLY `/tmp/` (all code, native modules)
+- **Persistent storage**: `~/navidocs/` (database, uploads, logs, config)
+- **Persistence risk**: `/tmp` may be cleared on reboot
+- **Security risk**: `/tmp` is readable by other StackCP users
+
+### 2. Service Constraints
+- **No local Redis**: Must use Redis Cloud (free 30MB tier)
+- **No local Tesseract**: Must use Google Cloud Vision API (free 1K pages/month)
+- **Meilisearch**: Already running on server (bonus)
+- **Process manager**: StackCP Node.js Manager (GUI-based) OR manual (nohup)
+
+### 3. Development Constraints
+- **npm execution**: Must use `/tmp/node /path/to/npm-cli.js` wrapper
+- **Native modules**: Must compile in `/tmp` (better-sqlite3, bcrypt)
+- **Path configuration**: All paths must be environment-configurable
+- **Deployment**: Code from Git to `/tmp`, data backups to `~`
+
+---
+
+## Architectural Impact
+
+### Code Changes Required (2-3 days)
+1. Centralized path configuration (`server/config/paths.js`)
+2. Update all file operations to use configurable paths
+3. Environment detection (local vs StackCP)
+4. Startup validation (fail fast if paths wrong)
+
+### Operational Changes Required (1-2 days)
+1. Daily checkpoint script (`/tmp` → `~/code-checkpoint/`)
+2. Health check script (detect `/tmp` code loss, auto-recover)
+3. Data backup script (SQLite + uploads, NOT code)
+4. Restore procedure (Git → `/tmp`, backups → data)
+
+### Documentation Changes Required (1-2 days)
+1. Rewrite QUICKSTART.md (split local vs StackCP)
+2. Update ARCHITECTURE-SUMMARY.md (add deployment constraints)
+3. Revise 2-week-launch-plan.md (StackCP-specific steps)
+4. Create deployment runbook
+
+**Total Effort**: 5-7 days focused work
+
+---
+
+## Key Questions for Debate
+
+### For Security Expert:
+
+1. **Risk Assessment**: `/tmp/navidocs` is readable by other StackCP users
+   - Threat: Source code exposure (including algorithm logic)
+   - Threat: `.env` symlink in `/tmp` could expose secrets
+   - Mitigation: Keep secrets in `~/navidocs/.env` (noexec but protected), symlink carefully
+   - **Question**: Is this acceptable risk for MVP, or blocker requiring VPS migration?
+
+2. **External Service Security**: Redis Cloud + Google Vision API
+   - Benefit: Managed services, professional security
+   - Risk: Network dependency, potential service compromise
+   - **Question**: Does cloud-first approach meet security requirements?
+
+3. **Code Integrity**: `/tmp` persistence risk
+   - Risk: Code could be cleared, replaced, or tampered with
+   - Mitigation: Daily checksums, auto-recovery from Git
+   - **Question**: Can we trust code integrity in `/tmp`?
+
+### For OCI Architect:
+
+1. **Container Alternative**: Should we abandon StackCP for containerized deployment?
+   - Option A: Docker on StackCP (if supported)
+   - Option B: Migrate to container hosting (Fly.io, Railway, etc.)
+   - Option C: DigitalOcean App Platform (container-based)
+   - **Question**: Is the StackCP complexity worth it vs. $5/month VPS?
+
+2. **Architecture Portability**: How to maintain deployment flexibility?
+   - Current: Local dev, StackCP prod
+   - Future: VPS, Kubernetes, serverless?
+   - **Question**: Should we design for StackCP OR design agnostic with StackCP adapter?
+
+3. **Operational Complexity**: Is this maintainable long-term?
+   - Custom scripts: checkpoint, health checks, recovery
+   - Two-location deployment: `/tmp` + `~`
+   - Manual monitoring: /tmp persistence
+   - **Question**: Does this operational overhead scale?
+
+### For Tech Lead:
+
+1. **Developer Experience**: How does this affect development workflow?
+   - Local dev: Standard npm, relative paths
+   - StackCP deploy: Wrapper scripts, absolute paths, manual recovery
+   - **Question**: Can we maintain DX while supporting StackCP?
+
+2. **Testing Strategy**: How to test StackCP-specific scenarios?
+   - Unit tests: Path configuration
+   - Integration tests: Checkpoint/restore
+   - E2E tests: Deployment on fresh StackCP account
+   - **Question**: What's the minimum viable test coverage?
+
+3. **Rollout Plan**: How to phase this in?
+   - Phase 1: Core path configuration (blocks everything else)
+   - Phase 2: Operational scripts (enables deployment)
+   - Phase 3: Documentation (enables users)
+   - Phase 4: Beta test on StackCP (validates assumptions)
+   - **Question**: Can we ship without full StackCP support first?
+
+---
+
+## Three Paths Forward
+
+### Path A: Full StackCP Adaptation (5-7 days)
+**Pros**:
+- Use existing hosting (no new costs)
+- Learn shared hosting constraints (educational)
+- Meilisearch already running (bonus)
+
+**Cons**:
+- Significant architecture changes
+- Operational complexity (checkpoint scripts, monitoring)
+- Security risks (`/tmp` exposure, external services)
+- Technical debt (StackCP-specific code)
+
+**Recommendation**: Only if StackCP hosting is **must-have** constraint
+
+---
+
+### Path B: Hybrid Approach (3-4 days)
+**Pros**:
+- Design path-agnostic architecture (good practice anyway)
+- Support StackCP as deployment option (not primary)
+- Maintain standard development workflow
+- Easy migration to VPS later
+
+**Cons**:
+- Still requires StackCP scripts and documentation
+- Testing complexity (multiple environments)
+- Partial investment in StackCP-specific tooling
+
+**Recommendation**: Best balance of flexibility and investment
+
+---
+
+### Path C: Abandon StackCP, Use VPS (1 day)
+**Pros**:
+- Standard deployment (PM2, systemd, local services)
+- Better security (isolated environment)
+- Simpler operations (single code location)
+- Lower technical debt
+- Easier to document and support
+
+**Cons**:
+- Additional cost ($5-10/month DigitalOcean/Linode)
+- Need to manage VPS (updates, security patches)
+- Lose Meilisearch bonus (need to install)
+
+**Recommendation**: Simplest path, industry-standard approach
+
+---
+
+## Cost Comparison
+
+### StackCP Deployment (Path A/B)
+```
+StackCP Hosting:         $X/month (already paying)
+Redis Cloud:             $0 (free 30MB tier)
+Google Vision API:       $0 (free 1K pages/month)
+Development time:        5-7 days (Path A) or 3-4 days (Path B)
+Operational overhead:    Ongoing (monitoring, checkpoints)
+---
+Total new cost:          $0/month
+Total time investment:   3-7 days + ongoing maintenance
+```
+
+### VPS Deployment (Path C)
+```
+DigitalOcean Droplet:    $6/month (1GB RAM, 25GB SSD)
+  OR Linode Nanode:      $5/month (1GB RAM, 25GB SSD)
+Development time:        1 day (standard deployment)
+Operational overhead:    Standard (systemd, cron backups)
+---
+Total new cost:          $5-6/month
+Total time investment:   1 day + standard VPS maintenance
+```
+
+### Real-World Scenarios
+
+**Small marina (50 manuals/month)**:
+- StackCP: $0 new cost, 5-7 days setup + ongoing overhead
+- VPS: $6/month, 1 day setup, minimal overhead
+
+**Medium marina (500 manuals/month)**:
+- StackCP: May exceed free tiers → $6-10/month for Redis + Vision
+- VPS: $6/month, can run all services locally
+
+**Verdict**: VPS is simpler and potentially cheaper at scale
+
+---
+
+## Security Risk Matrix
+
+| Risk | StackCP | VPS |
+|------|---------|-----|
+| Source code exposure | **HIGH** (`/tmp` readable) | **LOW** (isolated) |
+| Secrets exposure | **MEDIUM** (careful symlinks) | **LOW** (standard perms) |
+| External service compromise | **MEDIUM** (Redis/Google Cloud) | **LOW** (local services) |
+| Code tampering | **MEDIUM** (`/tmp` volatile) | **LOW** (standard deploy) |
+| Data breach | **LOW** (same in both) | **LOW** (same in both) |
+| DDoS vulnerability | **LOW** (shared IP protected) | **MEDIUM** (direct exposure) |
+
+**Overall Security**: VPS is more secure for production data
+
+---
+
+## Technical Debt Analysis
+
+### StackCP-Specific Technical Debt
+1. **Path configuration abstraction** (useful everywhere, low debt)
+2. **Checkpoint/recovery scripts** (StackCP-only, medium debt)
+3. **npm wrapper scripts** (StackCP-only, low debt)
+4. **Dual-location deployment logic** (StackCP-only, high debt)
+5. **Health checks for /tmp loss** (StackCP-only, medium debt)
+6. **StackCP-specific documentation** (maintenance burden)
+
+**Debt Score**: Medium-High (some useful, some waste)
+
+### VPS Technical Debt
+1. **Standard systemd services** (industry standard, no debt)
+2. **Standard backup scripts** (reusable, no debt)
+3. **PM2 process management** (industry standard, no debt)
+4. **VPS-specific documentation** (broadly useful, low debt)
+
+**Debt Score**: Low (standard practices)
+
+---
+
+## Recommendations for Debate
+
+### Tech Lead Perspective
+
+**Recommended Path**: **Path C (VPS)** for production, **Path B (Hybrid)** if StackCP is required
+
+**Reasoning**:
+1. **Developer Experience**: VPS maintains standard workflow, StackCP requires special handling
+2. **Time Investment**: 1 day (VPS) vs 5-7 days (StackCP) for same functionality
+3. **Operational Complexity**: VPS is industry-standard, StackCP requires custom tooling
+4. **Technical Debt**: VPS has minimal debt, StackCP accumulates StackCP-specific code
+5. **Security**: VPS provides better isolation and code integrity
+
+**Compromise Position** (if StackCP is required):
+- Implement **Path B (Hybrid)**: Path-agnostic core, StackCP adapter
+- Design for portability (easy VPS migration later)
+- Document StackCP as "advanced deployment option"
+- Use StackCP for MVP, migrate to VPS if successful
+
+### Security Considerations
+
+**Red Flags for StackCP**:
+1. `/tmp` code exposure to other users
+2. Code integrity concerns (volatility, tampering)
+3. External service dependencies (attack surface)
+
+**Acceptable if**:
+- No sensitive algorithms in code (open source anyway?)
+- Secrets properly protected in `~/navidocs/.env`
+- Health checks validate code integrity on startup
+- External services use strong authentication
+
+### OCI Considerations
+
+**StackCP is NOT container-friendly**:
+- No Docker support on shared hosting
+- Custom deployment model doesn't align with container best practices
+- Better alternatives: Fly.io ($0-5/month), Railway ($5/month), Render ($7/month)
+
+**If containerization is a goal**: Skip StackCP entirely, use container platform from day 1
+
+---
+
+## Decision Framework
+
+### Choose StackCP IF:
+- [ ] Already paying for StackCP hosting (sunk cost)
+- [ ] Cannot afford $5/month VPS (budget constraint)
+- [ ] Educational value of shared hosting constraints (learning)
+- [ ] Willing to accept security tradeoffs (low-risk data)
+- [ ] Have 5-7 days to invest in adaptation
+
+### Choose VPS IF:
+- [ ] Production security is priority (sensitive data)
+- [ ] Want standard deployment model (less complexity)
+- [ ] Need local services (Redis, Tesseract)
+- [ ] Future scalability important (easy horizontal scaling)
+- [ ] Want to ship MVP quickly (1 day vs 5-7 days)
+
+### Choose Container Platform IF:
+- [ ] Want modern deployment model (Dockerfile, Git push deploy)
+- [ ] Need auto-scaling (traffic spikes)
+- [ ] Multi-region deployment (future)
+- [ ] CI/CD integration (GitHub Actions → auto-deploy)
+- [ ] Budget allows ($5-10/month)
+
+---
+
+## Questions for Group Decision
+
+1. **Is StackCP hosting a hard requirement, or can we consider VPS?**
+   - If required: Why? (cost, existing account, other constraints?)
+   - If flexible: What's the decision criteria?
+
+2. **What's the risk tolerance for `/tmp` code exposure?**
+   - Is NaviDocs code open source anyway? (if yes, exposure is lower risk)
+   - Are there proprietary algorithms that must be protected?
+
+3. **What's the timeline for MVP launch?**
+   - If urgent: VPS is faster (1 day vs 5-7 days)
+   - If flexible: StackCP adaptation is feasible
+
+4. **What's the long-term vision for deployment?**
+   - Single-server: VPS is fine
+   - Multi-region: Container platform is better
+   - StackCP forever: Full adaptation needed
+
+5. **Who will maintain operational scripts?**
+   - If solo dev: VPS is simpler (less to maintain)
+   - If team: StackCP complexity is manageable
+
+---
+
+## Proposed Action Items
+
+### Immediate (Before Debate)
+- [ ] Verify `/tmp` persistence on StackCP (how often is it cleared?)
+- [ ] Test `/tmp` file permissions (can other users read?)
+- [ ] Confirm StackCP Node.js Manager capabilities
+- [ ] Price check: DigitalOcean vs Linode vs Fly.io vs Railway
+
+### If Choosing StackCP (Path A/B)
+- [ ] Implement `server/config/paths.js` (centralized configuration)
+- [ ] Create StackCP deployment scripts
+- [ ] Write operational scripts (checkpoint, health check, backup)
+- [ ] Test on StackCP with dummy app
+- [ ] Security review: `.env` protection, code exposure
+- [ ] Document StackCP-specific workflows
+
+### If Choosing VPS (Path C)
+- [ ] Sign up for VPS provider (DigitalOcean recommended)
+- [ ] Write standard deployment script (PM2 + systemd)
+- [ ] Install Meilisearch, Redis, Tesseract
+- [ ] Deploy NaviDocs with standard workflow
+- [ ] Set up backups (daily SQLite + uploads)
+- [ ] Document VPS deployment
+
+### If Choosing Container Platform
+- [ ] Create Dockerfile for NaviDocs
+- [ ] Test locally with Docker Compose
+- [ ] Choose platform (Fly.io, Railway, Render)
+- [ ] Set up CI/CD (GitHub Actions → auto-deploy)
+- [ ] Configure external services (managed Redis, Meilisearch)
+- [ ] Document container deployment
+
+---
+
+## Summary for Debate
+
+**Situation**: StackCP has unique constraints that require architectural changes
+**Options**: Full StackCP adaptation (5-7 days), Hybrid (3-4 days), VPS (1 day)
+**Recommendation**: VPS for production, Hybrid if StackCP required
+**Key Decisions Needed**:
+1. Is StackCP a hard requirement?
+2. What's the security risk tolerance?
+3. What's the MVP timeline?
+4. What's the long-term deployment vision?
+
+**Next Steps**: Debate, decide path, implement chosen approach
+
+---
+
+**Prepared by**: Tech Lead
+**Date**: 2025-10-19
+**For Review**: Security Expert, OCI Architect
+**Decision Deadline**: Before Phase 1 implementation begins
--- a/STACKCP_QUICK_REFERENCE.md
+++ b/STACKCP_QUICK_REFERENCE.md
@ -0,0 +1,343 @@
+# StackCP Deployment: Quick Reference Card
+
+**For**: Fast decision-making during technical debate
+**Date**: 2025-10-19
+
+---
+
+## The Core Problem
+
+```
+Standard Deployment:          StackCP Reality:
+~/navidocs/                   /tmp/navidocs/     ← Code (executable, volatile)
+├── server/                   ~/navidocs/        ← Data (noexec, persistent)
+├── uploads/
+└── db/                       Implications:
+                              - npm wrapper needed
+                              - Dual-location backups
+                              - Code persistence risk
+                              - Path abstraction required
+```
+
+---
+
+## Three Paths Forward (Decision Matrix)
+
+| Aspect | Path A: Full StackCP | Path B: Hybrid | Path C: VPS |
+|--------|---------------------|----------------|-------------|
+| **Time to Deploy** | 5-7 days | 3-4 days | 1 day |
+| **Monthly Cost** | $0 new | $0 new | $5-6 |
+| **Complexity** | High | Medium | Low |
+| **Security Risk** | Medium-High | Medium | Low |
+| **Technical Debt** | High | Medium | Low |
+| **Maintenance** | Ongoing custom | Some custom | Standard |
+| **Scalability** | Limited | Good | Excellent |
+| **Developer DX** | Poor | Fair | Excellent |
+
+---
+
+## Critical Architectural Changes (All Paths Need Some)
+
+### Required for StackCP (Path A/B)
+```javascript
+// server/config/paths.js
+export const DATABASE_PATH = process.env.DATABASE_PATH ||
+  (isStackCP ? '~/navidocs/db/navidocs.db' : './db/navidocs.db');
+
+// Checkpoint script (daily cron)
+rsync -av /tmp/navidocs/ ~/navidocs/code-checkpoint/
+
+// Health check (every 6 hours)
+if [ ! -f /tmp/navidocs/server/index.js ]; then
+  restore_from_checkpoint_or_git
+fi
+```
+
+### Required for Any Deployment (Good Practice)
+```javascript
+// Environment-based configuration
+const CONFIG = {
+  databasePath: process.env.DATABASE_PATH,
+  uploadDir: process.env.UPLOAD_DIR,
+  logDir: process.env.LOG_DIR
+};
+
+// Startup validation
+if (!fs.existsSync(CONFIG.databasePath)) {
+  throw new Error(`Database path not found: ${CONFIG.databasePath}`);
+}
+```
+
+---
+
+## Security Risk Assessment
+
+### StackCP-Specific Risks
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| `/tmp` code readable by others | **HIGH** | Open source anyway? |
+| Code tampering/replacement | **MEDIUM** | Checksum validation on startup |
+| Secrets in `/tmp` symlinks | **HIGH** | Keep `.env` in `~/navidocs/` only |
+| External service compromise | **MEDIUM** | Use managed services (Redis Cloud) |
+
+### VPS Risks (for comparison)
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| Direct internet exposure | **MEDIUM** | Firewall, fail2ban |
+| Unpatched vulnerabilities | **MEDIUM** | Auto-updates, monitoring |
+| Root access compromise | **HIGH** | SSH keys, no root login |
+
+**Verdict**: VPS has standard, well-understood risks; StackCP has novel risks
+
+---
+
+## Cost Analysis (Real Numbers)
+
+### StackCP Option
+```
+Setup time:           5-7 days (Path A) or 3-4 days (Path B)
+Developer hourly:     $50-100/hour (if billing)
+Setup cost:           $2,000-2,800 (5-7 days × 8 hours × $50)
+Monthly recurring:    $0 (within free tiers)
+Operational time:     2-4 hours/month (monitoring, checkpoints)
+Operational cost:     $100-200/month
+
+TOTAL YEAR 1:         $2,000-2,800 (setup) + $1,200-2,400 (ops) = $3,200-5,200
+```
+
+### VPS Option
+```
+Setup time:           1 day
+Setup cost:           $400 (1 day × 8 hours × $50)
+Monthly recurring:    $6/month (DigitalOcean)
+Operational time:     0.5-1 hour/month (standard maintenance)
+Operational cost:     $25-50/month
+
+TOTAL YEAR 1:         $400 (setup) + $72 (VPS) + $300-600 (ops) = $772-1,072
+```
+
+**Savings with VPS**: $2,400-4,100 in Year 1
+
+---
+
+## Decision Tree
+
+```
+START
+  |
+  ├─ Is StackCP a hard requirement? ────YES──→ Is security acceptable? ──YES──→ Path A/B (StackCP)
+  |                                     |                                 └──NO───→ Escalate (need VPS)
+  |                                     |
+  └─────────────NO──────────────────────┘
+                                        |
+                                        ├─ Budget < $6/month? ──YES──→ Path A/B (StackCP, accept tradeoffs)
+                                        |                       └──NO───→ Path C (VPS recommended)
+                                        |
+                                        └─ Need containers? ────YES──→ Container platform (Fly.io, Railway)
+                                                               └──NO───→ Path C (VPS)
+```
+
+---
+
+## Key Questions (Answer in < 5 min)
+
+1. **Why StackCP?** (check all that apply)
+   - [ ] Already paying for it (sunk cost)
+   - [ ] Cannot afford $6/month VPS
+   - [ ] Educational/learning exercise
+   - [ ] Other: _______________________
+
+2. **Security posture** (choose one)
+   - [ ] Open source project (code exposure OK)
+   - [ ] Proprietary algorithms (code must be protected)
+   - [ ] Sensitive user data (high security required)
+
+3. **Timeline** (choose one)
+   - [ ] Ship MVP in 1 week (VPS recommended)
+   - [ ] Ship MVP in 2-3 weeks (StackCP feasible)
+   - [ ] No rush (either works)
+
+4. **Long-term vision** (choose one)
+   - [ ] Personal/small project (StackCP or VPS fine)
+   - [ ] Startup/growth (VPS or container platform)
+   - [ ] Enterprise/multi-region (container platform)
+
+5. **Maintenance capacity** (choose one)
+   - [ ] Solo dev, minimal time (VPS recommended)
+   - [ ] Team, can handle custom ops (StackCP OK)
+   - [ ] DevOps team (either works)
+
+---
+
+## Recommendation Algorithm
+
+```python
+def recommend_deployment(answers):
+    # Hard requirements
+    if answers.stackcp_required and not answers.security_acceptable:
+        return "ESCALATE: Need VPS but StackCP required"
+
+    if answers.stackcp_required and answers.security_acceptable:
+        return "Path B: Hybrid (support StackCP, plan migration)"
+
+    # Budget-driven
+    if answers.budget < 6 and answers.timeline > 2_weeks:
+        return "Path A: Full StackCP (if time allows)"
+
+    # Default: VPS is simplest
+    if answers.timeline <= 1_week or answers.security_high:
+        return "Path C: VPS (standard deployment)"
+
+    # Containers for scale
+    if answers.long_term == "startup" or answers.long_term == "enterprise":
+        return "Container Platform (Fly.io, Railway)"
+
+    # Fallback
+    return "Path C: VPS (safest choice)"
+```
+
+---
+
+## What Changes in Each Path
+
+### Path A: Full StackCP Adaptation
+**Code**:
+- ✅ `server/config/paths.js` (centralized)
+- ✅ All file operations use config
+- ✅ Environment detection (local vs StackCP)
+- ✅ Startup validation
+
+**Scripts**:
+- ✅ `/tmp/npm` wrapper
+- ✅ `checkpoint-navidocs-code` (daily)
+- ✅ `check-navidocs-code` (health check)
+- ✅ `backup-navidocs-data` (database + uploads)
+- ✅ `restore-navidocs` (Git + data restore)
+
+**Docs**:
+- ✅ QUICKSTART-STACKCP.md
+- ✅ ARCHITECTURE-SUMMARY.md (add constraints)
+- ✅ 2-week-launch-plan.md (StackCP steps)
+
+**Cron Jobs**:
+- ✅ Daily checkpoint
+- ✅ Daily data backup
+- ✅ 6-hour health check
+
+### Path B: Hybrid (Recommended Compromise)
+**Code**:
+- ✅ `server/config/paths.js` (useful everywhere)
+- ✅ Environment variables for all paths
+- ⚠️ Skip StackCP-specific health checks (document manual recovery)
+
+**Scripts**:
+- ✅ `scripts/stackcp/deploy.sh` (StackCP-specific)
+- ✅ `scripts/local/dev.sh` (local development)
+- ⚠️ Minimal StackCP operational scripts (document, don't automate)
+
+**Docs**:
+- ✅ Split local vs StackCP guides
+- ✅ Document StackCP as "advanced option"
+- ⚠️ Warn about operational complexity
+
+### Path C: VPS (Simplest)
+**Code**:
+- ⚠️ Optional: Path configuration (good practice, not required)
+- ⚠️ No StackCP-specific code
+
+**Scripts**:
+- ✅ Standard PM2 ecosystem file
+- ✅ Standard systemd service
+- ✅ Standard backup script (single location)
+
+**Docs**:
+- ✅ Standard VPS deployment guide
+- ✅ systemd + PM2 setup
+- ✅ Standard operations (restart, logs, backups)
+
+---
+
+## Immediate Actions (Next 60 Minutes)
+
+### If Choosing StackCP
+1. **Verify** `/tmp` persistence (ask StackCP support)
+2. **Test** `/tmp` permissions (can other users read?)
+3. **Create** `server/config/paths.js` (30 min)
+4. **Write** `.env.stackcp.example` (15 min)
+5. **Draft** checkpoint script (15 min)
+
+### If Choosing VPS
+1. **Sign up** DigitalOcean or Linode (5 min)
+2. **Deploy** Ubuntu 22.04 droplet (2 min)
+3. **Install** Node.js, PM2, Meilisearch, Redis (20 min)
+4. **Deploy** NaviDocs with standard process (20 min)
+5. **Test** upload + search (13 min)
+
+### If Choosing Container Platform
+1. **Create** Dockerfile (20 min)
+2. **Test** locally with docker-compose (15 min)
+3. **Sign up** Fly.io or Railway (5 min)
+4. **Deploy** via CLI (10 min)
+5. **Test** production deployment (10 min)
+
+---
+
+## Red Flags (Abort Criteria)
+
+### StackCP is NOT viable if:
+- [ ] `/tmp` is cleared daily (code loss risk too high)
+- [ ] Cannot get `/tmp/node` to work (no workaround)
+- [ ] StackCP blocks long-running processes (workers fail)
+- [ ] Security review rejects `/tmp` code exposure
+- [ ] Timeline is < 2 weeks (not enough time)
+
+### VPS is NOT viable if:
+- [ ] Literally $0 budget (but then how is StackCP paid?)
+- [ ] Cannot manage server (no SSH skills)
+- [ ] Regulatory requirement for shared hosting (rare)
+
+---
+
+## Final Recommendation (Tech Lead)
+
+**Default Choice: Path C (VPS)**
+
+**Reasons**:
+1. **Time**: 1 day vs 5-7 days (4-6 days saved)
+2. **Cost**: $772/year vs $3,200/year (77% savings)
+3. **Security**: Standard risks vs novel risks
+4. **Maintenance**: Standard ops vs custom scripts
+5. **Scalability**: Easy horizontal scaling vs limited
+
+**Acceptable Alternative: Path B (Hybrid)**
+
+**If**:
+- StackCP is already paid for (sunk cost)
+- Educational value is important (learn constraints)
+- Timeline allows 3-4 days
+- Security risks are acceptable (open source project)
+
+**NOT Recommended: Path A (Full StackCP)**
+
+**Unless**:
+- StackCP is absolute hard requirement (contractual?)
+- Have dedicated team for custom operations
+- Plan to productize StackCP deployment (sell as service)
+
+---
+
+## Debate Checklist
+
+Before ending debate, ensure consensus on:
+- [ ] **Chosen path**: A, B, or C?
+- [ ] **Timeline**: When to complete implementation?
+- [ ] **Owner**: Who implements the chosen path?
+- [ ] **Review**: Who reviews security/architecture?
+- [ ] **Fallback**: What if chosen path fails?
+- [ ] **Metrics**: How to measure success?
+
+---
+
+**Prepared by**: Tech Lead
+**Decision Time**: < 30 minutes recommended
+**Implementation Start**: Immediately after decision