Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 7 additions & 10 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -751,28 +751,25 @@ Deliverables:
frontend/ (React + D3.js or React Flow)
Dashboard: decision timeline, coverage heatmap, contradiction queue
Graph explorer: interactive Neo4j visualization
Animated GIF for README (demo scenario)
Animated GIF for README (demo scenario via generate_readme_demo_gif.py)

Done when:
Dashboard loads in < 2 seconds
Graph explorer navigable without instructions
GIF captures the "new engineer asks why CockroachDB?" demo
README GIF captures the memory-fabric demo path
```

### Phase 7 — Open-source launch (Week 5)
### Phase 7 — Live demo + README polish (Week 5)
```
Deliverables:
README.md final polish
docker-compose.yml tested on clean machine (no residual config)
3-minute Loom demo video
Animated GIF in README
Hacker News "Show HN" post
LinkedIn post
dev.to technical writeup
Public live demo URL
README memory-fabric GIF (scripts/generate_readme_demo_gif.py)

Done when:
Fresh clone + docker-compose up + working demo in < 10 minutes
HN post submitted
Fresh clone + make demo + working local demo
Live dashboard URL linked from README
```

---
Expand Down
14 changes: 7 additions & 7 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,10 +93,10 @@ LinkedIn: linkedin.com/in/abhinaysai-kamineni

## Current Phase

**Phase:** 7 — Demo launch + open-source polish
**Status:** Phase 6 dashboard stack complete on `feat/ui-qa-a11y`; merge to `main` in progress
**Next phase:** Phase 8 — Outcome tracking + coverage scoring (post-launch)
**Target:** Working public demo URL + README launch
**Phase:** 8 — Outcome tracking + coverage scoring
**Status:** Phase 7 complete — live demo URL + README polish on `main` (set `CORTEX_API_ORIGIN` on Vercel for API-backed search)
**Next phase:** Phase 8 deliverables (coverage scorer, outcome linker)
**Target:** Coverage score on every query + outcome-linked decisions in the graph

---

Expand All @@ -111,7 +111,7 @@ LinkedIn: linkedin.com/in/abhinaysai-kamineni
| 4 | Importance scorer + trust scorer + RBAC | Week 2-3 | ✅ Done |
| 5 | Contradiction detector + decay engine | Week 3 | ✅ Done |
| 6 | React dashboard + knowledge graph explorer | Week 3-4 | ✅ Done |
| 7 | Demo video + README polish + open-source launch | Week 4 | ⏳ |
| 7 | Live demo URL + README polish | Week 4 | ✅ Done |
| 8 | Outcome tracking + coverage scoring | Post-launch | ⏳ |
| 9 | Behavioral mining + elicitation bot | Post-launch | ⏳ |
| 10 | Federated cross-org memory | v2 | ⏳ |
Expand All @@ -127,8 +127,8 @@ LinkedIn: linkedin.com/in/abhinaysai-kamineni
| Local LLM | Ollama + Gemma 4 E4B — ~10GB RAM, 8-12 tok/s CPU |
| Secondary | MacBook Air (development), iPhone (SSH via Termius + Tailscale) |
| Cloud budget | Minimize — free tiers only for MVP |
| Timeline | 4-week MVP, open-source launch week 5 |
| Portfolio goal | Demo-able in under 3 minutes. GitHub README must be self-explanatory. |
| Timeline | 4-week MVP |
| Portfolio goal | Demo-able via live URL + `make demo`. GitHub README must be self-explanatory. |

---

Expand Down
9 changes: 5 additions & 4 deletions DECISIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -217,21 +217,22 @@ access_policy: {

---

### D-012 — 2026-05-11 — 4-week MVP, open-source launch week 5
### D-012 — 2026-05-11 — 4-week MVP
**Status:** Active
**Decision:** MVP shipped in 4 weeks. Open-source launch (HN, LinkedIn, dev.to) in week 5.
**Decision:** MVP shipped in 4 weeks.
**MVP scope:**
- Slack + GitHub connectors
- Decision extractor + importance scorer (basic)
- Neo4j graph with core schema
- `cortex.query()` REST API
- MCP server
- React dashboard (read-only, graph explorer)
- Demo video (3 min max)
- README with animated GIF
- README with memory-fabric GIF
- Live demo URL
**NOT in MVP:** Trust scorer, contradiction detector, decay engine, outcome tracker, Jira/Linear connectors, RBAC (basic auth only), elicitation bot
**Rationale:** Ship something real. Extend after traction. The Jira connector, decay engine, and RBAC can be added as community contributions once the repo has stars.
**Owner:** Abhinaysai
**[UPDATE 2026-09-17]:** Demo video recording, release tagging, and social launch posts (Show HN / LinkedIn / Loom) are out of scope — removed from Phase 7 and operating docs.

---

Expand Down
16 changes: 7 additions & 9 deletions MISTAKES.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,14 +86,12 @@
### [M-006] — 2026-05-11 — No demo video in initial scope
**Phase:** Phase 0
**Type:** Product / Process
**What happened:** Launch plan included HN post and LinkedIn post. No demo video or animated GIF for README.
**Why it happened:** Focused on technical build, not distribution.
**Impact:** Open-source repos without demo GIFs get significantly fewer stars. HN "Show HN" posts without live demos get fewer upvotes. The technical work becomes invisible.
**Fix / Learning:** Week 4 deliverable must include:
- 3-minute Loom demo video (new engineer asking Cursor "why CockroachDB?" → Cortex returns full decision history)
- Animated GIF for README (same scenario, compressed to 30 seconds)
- Plan this in advance — not bolted on after the fact
**Prevents:** Shipping a working product that nobody engages with.
**Status:** SUPERSEDED 2026-09-17 — demo video / Loom / Show HN / LinkedIn launch posts removed from scope
**What happened:** Launch plan originally included HN/LinkedIn posts and a Loom demo video plus README GIF.
**Why it happened:** Focused on technical build, then over-indexed on distribution checklist items.
**Impact:** Open checklist items blocked Phase 7 closure even after live demo URL + README GIF shipped.
**Fix / Learning:** Phase 7 closes on live demo URL + README polish (including generated memory-fabric GIF). Do not block product work on manual video recording or social announcement posts.
**Prevents:** Scope creep that keeps “launch” forever open after the product is demo-able.

---

Expand Down Expand Up @@ -140,5 +138,5 @@

### [L-005] — 2026-05-11 — Four-week MVP discipline
**What:** Full architecture includes trust scorer, RBAC, contradiction detector, decay engine, outcome tracker, behavioral mining, federated memory. If all of that is Phase 1, nothing ships.
**Why it matters:** Portfolio project needs a demo in 4 weeks. Open-source project needs stars in 5 weeks. The job search timeline is real. MVP is: Slack + GitHub connectors + Neo4j graph + MCP server + basic dashboard + demo video. Everything else is post-launch.
**Why it matters:** Portfolio project needs a working demo in 4 weeks. The job search timeline is real. MVP is: Slack + GitHub connectors + Neo4j graph + MCP server + basic dashboard + live demo URL. Everything else is post-launch.
**Apply to:** Every temptation to add "just one more feature" before shipping — check the 4-week constraint first.
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -227,7 +227,7 @@ This brings up Kafka, Neo4j, Redis, Postgres, applies graph migrations, writes t

**Dashboard looks stale?** The UI is served from a Docker image on port **3000**. Rebuild with `docker compose --profile api --profile frontend build frontend && docker compose --profile api --profile frontend up -d --force-recreate frontend`, then hard-refresh the browser (`Cmd+Shift+R`). For hot reload during UI work, run `cd frontend && npm run dev` → [http://localhost:5173](http://localhost:5173) (dev server uses **5173** so it does not clash with Docker).

**Recording a video or GIF for the README:** see [docs/DEMO_RECORDING.md](docs/DEMO_RECORDING.md). **Validating real webhooks (Slack / GitHub / Jira):** [docs/CONNECTOR_VALIDATION.md](docs/CONNECTOR_VALIDATION.md).
**Validating real webhooks (Slack / GitHub / Jira):** [docs/CONNECTOR_VALIDATION.md](docs/CONNECTOR_VALIDATION.md).

### Context API (REST)

Expand Down Expand Up @@ -387,7 +387,7 @@ cortex/
| Phase 4 | Importance + trust scoring + graph RBAC | ✅ Shipped |
| Phase 5 | Contradiction detector + decay engine | ✅ Shipped |
| Phase 6 | React dashboard (Ask, memory map, guide, agent inject) | ✅ Shipped |
| Phase 7 | Live demo URL + demo video + open-source launch | 🔄 In progress |
| Phase 7 | Live demo URL + README polish | ✅ Done (wire `CORTEX_API_ORIGIN` for API-backed search) |
| Phase 8 | Outcome tracking + coverage scoring | ⏳ Post-launch |
| Phase 9 | Elicitation bot (implicit knowledge) | ⏳ Post-launch |
| Phase 10 | Federated cross-org memory | ⏳ v2 |
Expand Down
55 changes: 39 additions & 16 deletions SESSIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -197,13 +197,12 @@

### State at end
- 207 pytest tests passing
- Phase 7 launch items (video, HN post) remain manual owner tasks
- Phase 7 focus: live demo URL + README polish (demo video / social launch posts out of scope)

### Next session starts with
1. ~~Run `python -m graph.migrate` (apply V006)~~ — superseded: migrations through **V007**; use `make demo` or `python -m graph.migrate` after schema changes (see Session 4).
2. `docker compose --profile api up` and validate **webhook → worker → graph** on a dev workspace (Slack/GitHub tokens in `.env`).
3. Phase 7: screen recording + README GIF — follow [docs/DEMO_RECORDING.md](docs/DEMO_RECORDING.md).

3. Phase 7: public live demo URL in README + README polish.
---

## Session 3 — 2026-05-14
Expand Down Expand Up @@ -239,16 +238,15 @@
- `graph/migrations` — **V007** fulltext repair; **V001–V006** `SchemaVersion` **MERGE (v {version}) SET** (stable identity); **V001** dropped Enterprise-only property-existence constraint for Neo4j Community
- `.github/workflows/ci.yml` — **pytest** + **`scripts/seed_demo.py --dry-run`** on Python 3.11
- `tests/graph/test_migrate_strip.py` — unit tests for migration chunk stripping
- `docs/DEMO_RECORDING.md` — Phase 7 recording / GIF checklist; README links to it
- `docs/CONNECTOR_VALIDATION.md` — webhook → Kafka validation steps (GitHub / Slack / Jira); README links to it

### State at end
- **213** pytest passes; CI workflow ready for GitHub Actions on `main` / `develop` / PRs

### Next session starts with
1. **Owner:** Record demo + GIF per [docs/DEMO_RECORDING.md](docs/DEMO_RECORDING.md); add link in README when hosted
2. **Live connector path:** Slack (or GitHub) webhook → Kafka → worker → graph on a real workspace (tokens in `.env`)
3. **Optional:** Slim `api` Docker image (extras in `pyproject.toml`) so CI/local `docker compose build` is not dominated by Torch/spaCy unless needed for that image
1. **Live connector path:** Slack (or GitHub) webhook → Kafka → worker → graph on a real workspace (tokens in `.env`)
2. **Optional:** Slim `api` Docker image (extras in `pyproject.toml`) so CI/local `docker compose build` is not dominated by Torch/spaCy unless needed for that image
3. Phase 7: public live demo URL + README polish

---

Expand Down Expand Up @@ -290,9 +288,9 @@
- **228** pytest passes (~80% coverage)

### Next session starts with
1. Owner demo recording ([docs/DEMO_RECORDING.md](docs/DEMO_RECORDING.md))
2. Live webhook validation with real Slack/GitHub/Linear tokens
3. Optional: graph explorer UI tab calling `/decisions/.../chain`
1. Live webhook validation with real Slack/GitHub/Linear tokens
2. Optional: graph explorer UI tab calling `/decisions/.../chain`
3. Phase 7: public live demo URL + README polish

---

Expand Down Expand Up @@ -393,7 +391,7 @@
### Next session starts with
1. Merge live E2E PR; configure real Slack app webhook
2. Optional: slim pipeline-worker Docker image (worker-only deps)
3. Demo recording per `docs/DEMO_RECORDING.md`
3. Phase 7: public live demo URL + README polish

---

Expand Down Expand Up @@ -506,7 +504,7 @@
### Next session starts with
1. Merge PR #14 after CI green
2. LLM-backed CMVK verifiers (production)
3. Phase 6: dashboard polish + demo video
3. Phase 6: dashboard polish

---

Expand All @@ -526,7 +524,7 @@

### Next session starts with
1. Merge PR #15 after CI green
2. Phase 6: dashboard polish + demo video
2. Phase 6: dashboard polish
3. Staging smoke with `CORTEX_CMVK_BACKEND=openai`

---
Expand Down Expand Up @@ -554,7 +552,7 @@
### Next session starts with
1. Merge `feat/ui-qa-a11y` → `main` PR when CI green
2. Execute Plan A deploy per `docs/DEPLOY-FREE.md`
3. Phase 7: live demo URL in README + 3-minute demo video
3. Phase 7: live demo URL in README

---

Expand All @@ -576,5 +574,30 @@

### Next session starts with
1. Set `CORTEX_API_ORIGIN` on Vercel after Render API deploy (Plan A)
2. Record 3-minute demo video per `docs/DEMO_RECORDING.md`
3. GitHub release tag `v0.1.0` + open-source announcement
2. Phase 8: coverage scorer + outcome linker
3. High-priority OSS backlog: #33 cache invalidation, #36 decay scheduler

---

## Session — 2026-09-17 — Remove demo video / launch announcement scope
**Duration:** ~20m
**Phase:** Phase 7 closeout → Phase 8

### Built
- Deleted **`docs/DEMO_RECORDING.md`** (Loom / video / GIF recording checklist out of scope)
- Removed demo-video, `v0.1.0` tag, Show HN / LinkedIn / open-source announcement from operating docs
- Marked Phase 7 complete (live demo URL + README polish); advanced current phase to Phase 8
- Updated: `README.md`, `CLAUDE.md`, `ARCHITECTURE.md`, `DECISIONS.md` (D-012), `MISTAKES.md` (M-006 superseded, L-005), `docs/PRODUCTION_READINESS.md`, `SESSIONS.md` next-steps

### State at end
- Phase 7 no longer blocked on manual video or social launch posts
- Remaining deploy ops: set `CORTEX_API_ORIGIN` for API-backed public demo
- Next product work: Phase 8 coverage + outcomes

### Decisions made
- D-012 update: demo video / release tagging / social launch posts removed from Phase 7 scope

### Next session starts with
1. Set `CORTEX_API_ORIGIN` on Vercel after Render API deploy (Plan A)
2. Implement coverage scorer (`coverage_score` on `/query`)
3. Implement outcome linker (schema already in V004)
36 changes: 0 additions & 36 deletions docs/DEMO_RECORDING.md

This file was deleted.

3 changes: 1 addition & 2 deletions docs/PRODUCTION_READINESS.md
Original file line number Diff line number Diff line change
Expand Up @@ -221,8 +221,7 @@ Already present and correct: `.env`, `node_modules/`, `__pycache__/`, `.pytest_c
- [ ] Push `feature/production-refinement`
- [ ] Open PR → `main`
- [ ] CI green on PR
- [ ] Staging: `docker compose up` + seed + manual 3-min demo
- [ ] Tag release `v0.1.0` (optional)
- [ ] Staging: `docker compose up` + seed + manual demo walkthrough

---

Expand Down
Loading