nexus-cli 0.5.2__tar.gz → 0.6.1__tar.gz

nexus_cli-0.6.1/.STATUS

@@ -0,0 +1,102 @@
+status: active
+priority: 1
+progress: 100
+next: vault.py coverage 78% → 98.14% ✓ (last v0.6.0 target met, on dev). Ready for v0.6.1 patch release when desired
+type: dev
+checkpoint: 2026-06-03 — v0.6.0 FULLY SHIPPED. PR #6 reviewed+fixed (6 issues)+merged; PR #8 dev→main merged; tagged v0.6.0; PyPI published; docs site deployed; CI green (Windows fixed). Homebrew tap formula pushed (commit ef8bc03) + brew audit clean. All release channels live.
+version: 0.6.0
+release_date: 2026-06-03
+release_url: https://github.com/Data-Wise/nexus-cli/releases/tag/v0.6.0
+docs_url: https://data-wise.github.io/nexus-cli/
+planning_doc: ORCHESTRATE-nexus-enhancement.md
+
+worktrees: []
+
+# ═══════════════════════════════════════════════════════════════════
+# Nexus CLI - Knowledge Workflow for Research, Teaching, Writing
+# ═══════════════════════════════════════════════════════════════════
+
+🔧 Nexus CLI Development Status
+────────────────────────────────────────
+
+📍 LOCATION
+~/projects/dev-tools/nexus-cli/
+
+⏰ LAST UPDATED
+2026-06-02 — v0.5.2 shipped, full type safety achieved
+
+────────────────────────────────────────
+
+🎉 RELEASE v0.5.2 - FULL TYPE SAFETY
+
+Release highlights:
+- ✅ 0 mypy errors across all 18 source files (fixed 142)
+- ✅ TYPE_CHECKING imports + return type annotations on all _get_* helpers
+- ✅ dict[str, Any] throughout domain modules
+- ✅ PyPI published via OIDC Trusted Publishing (automatic on release)
+- ✅ Homebrew tap auto-updated via CI
+
+────────────────────────────────────────
+
+🎯 CURRENT STATUS
+
+**v0.5.2 SHIPPED** ✅
+
+📊 PROJECT METRICS (2026-06-02)
+
+Version: 0.5.2
+Tests: 499 passing, 1 skipped (76.81% coverage)
+Mypy: 0 errors across 18 source files ✅
+Commands: 50+ across 4 domains
+Tutorial Steps: 30 (7 + 11 + 12)
+Module Coverage highlights:
+  - Zotero: 96.89% 🚀
+  - Tutorial: 94.2% 🎓
+  - Quarto: 91.36%
+Documentation: 9,500+ lines (MkDocs)
+Python: 3.11+ required
+
+────────────────────────────────────────
+
+🎯 NEXT: v0.6.0 Coverage Push (per ORCHESTRATE plan)
+
+Coverage targets:
+- [ ] Knowledge (vault.py): 78% → 95%
+- [ ] Teaching (courses.py): 70% → 90%
+- [ ] Writing (bibliography.py): 74% → 90%
+- [ ] CLI (cli.py): improve overall
+
+Start with feature/courses-coverage worktree per ORCHESTRATE-nexus-enhancement.md
+
+────────────────────────────────────────
+
+🔗 RELATED PROJECTS
+
+| Project | Status | Purpose |
+|---------|--------|---------|
+| Nexus CLI | ✅ v0.5.2 | This project |
+| Nexus MCP Server | ✅ Active | 17 tools for Claude integration |
+| homebrew-tap | ✅ Auto-updated | brew install nexus-cli |
+
+────────────────────────────────────────
+
+📁 KEY FILES
+
+Core:
+- nexus/cli.py                  - Main CLI (TYPE_CHECKING imports added)
+- nexus/utils/tutorial.py       - Tutorial engine (94.2% coverage)
+- nexus/research/zotero.py      - Zotero integration (96.89% coverage)
+- pyproject.toml                - Project metadata (v0.5.2)
+
+CI/CD:
+- .github/workflows/publish.yml      - PyPI auto-publish on release (OIDC)
+- .github/workflows/homebrew-release.yml - Homebrew tap auto-update
+
+Planning:
+- ORCHESTRATE-nexus-enhancement.md  - v0.6.0 implementation plan
+- PLANNING.md                       - Development roadmap
+
+────────────────────────────────────────
+
+✅ v0.5.2 RELEASED - 2026-06-02
+📊 499 tests, 76.81% coverage, 0 mypy errors, full release pipeline automated

{nexus_cli-0.5.2 → nexus_cli-0.6.1}/.github/workflows/ci.yml

@@ -2,9 +2,9 @@ name: CI
 
 on:
   push:
-    branches: [ main, develop ]
+    branches: [ main, dev, develop ]
   pull_request:
-    branches: [ main, develop ]
+    branches: [ main, dev, develop ]
   workflow_dispatch:
 
 jobs:

{nexus_cli-0.5.2 → nexus_cli-0.6.1}/.github/workflows/homebrew-release.yml

@@ -59,4 +59,10 @@ jobs:
       source_type: pypi
       auto_merge: ${{ github.event.inputs.auto_merge == 'true' || github.event_name == 'workflow_dispatch' }}
     secrets:
+      # Prefer GitHub App auth (short-lived, scoped, no expiry to rotate).
+      # The reusable workflow mints an App token and only falls back to
+      # tap_token (an expiring PAT) when the App secrets are absent.
+      # Matches craft's pattern — see homebrew-tap update-formula.yml.
+      app_id: ${{ secrets.APP_ID }}
+      app_private_key: ${{ secrets.APP_PRIVATE_KEY }}
       tap_token: ${{ secrets.HOMEBREW_TAP_GITHUB_TOKEN }}

{nexus_cli-0.5.2 → nexus_cli-0.6.1}/.github/workflows/quality.yml

@@ -2,9 +2,9 @@ name: Code Quality
 
 on:
   push:
-    branches: [ main, develop ]
+    branches: [ main, dev, develop ]
   pull_request:
-    branches: [ main ]
+    branches: [ main, dev ]
   workflow_dispatch:
 
 jobs:

{nexus_cli-0.5.2 → nexus_cli-0.6.1}/.github/workflows/test.yml

@@ -2,9 +2,9 @@ name: Tests
 
 on:
   push:
-    branches: [ main, develop ]
+    branches: [ main, dev, develop ]
   pull_request:
-    branches: [ main ]
+    branches: [ main, dev ]
   schedule:
     # Run tests every Monday at 9 AM UTC
     - cron: '0 9 * * 1'
@@ -93,6 +93,9 @@ jobs:
 
     - name: Create coverage badge
       uses: schneegans/dynamic-badges-action@v1.7.0
+      # Non-blocking: gistID is an unconfigured placeholder. Until a real
+      # Gist + GIST_SECRET are set up, this step must not fail the workflow.
+      continue-on-error: true
       if: github.event_name == 'push' && github.ref == 'refs/heads/main'
       with:
         auth: ${{ secrets.GIST_SECRET }}

{nexus_cli-0.5.2 → nexus_cli-0.6.1}/CLAUDE.md

@@ -13,13 +13,13 @@ Nexus is a **knowledge workflow CLI** for academic researchers. It provides data
 - Teaching materials
 - Manuscripts
 
-**Current Version**: 0.5.2
+**Current Version**: 0.6.1
 
 ## Quick Start for Claude
 
 ```bash
 # Check installation
-nexus --version              # Should show 0.5.2
+nexus --version              # Should show 0.6.1
 nexus doctor                 # Health check
 
 # Interactive learning system
@@ -45,9 +45,12 @@ nexus-cli/
 │   ├── writing/             # ✍️ Manuscripts, LaTeX, bibliography
 │   ├── knowledge/           # 🧠 Vault, search, graph
 │   ├── integrations/        # 🔌 aiterm, R, Git
+│   ├── data/                # Bundled package data
+│   │   └── vault-spec.yaml  # Default PARA vault structure spec
 │   └── utils/               # Config, tutorial, output
 │       ├── config.py        # Configuration management
-│       └── tutorial.py      # Interactive tutorial system (NEW v0.5.0)
+│       ├── tutorial.py      # Interactive tutorial system (NEW v0.5.0)
+│       └── vault_spec.py    # Vault structure validation (PARA spec)
 │
 ├── plugin/                   # Claude Code plugin
 │   ├── skills/              # Domain skills
@@ -60,7 +63,7 @@ nexus-cli/
 │   ├── reference/           # CLI, API, MCP reference
 │   └── development/         # Contributing, testing
 │
-├── tests/                    # pytest tests (500 tests, 76.65% coverage)
+├── tests/                    # pytest tests (499 tests, 76.81% coverage)
 ├── config/                   # Default configs
 ├── pyproject.toml           # Project metadata
 └── README.md
@@ -179,8 +182,8 @@ nexus knowledge search "mediation" --source zotero,vault
 ## Development Commands
 
 ```bash
-# Install dependencies
-uv sync
+# Install dependencies (--all-extras required for dev tools)
+uv sync --all-extras
 
 # Run CLI locally
 uv run nexus --help
@@ -192,8 +195,8 @@ uv tool install .
 uv tool install --reinstall .  # For updates
 
 # Run tests
-uv run pytest                  # All tests (422 tests)
-uv run pytest --cov=nexus     # With coverage (75%)
+uv run pytest                  # All tests (499 tests)
+uv run pytest --cov=nexus     # With coverage (76.81%)
 uv run pytest tests/research/ # Specific domain
 
 # Type check
@@ -233,7 +236,10 @@ writing:
   manuscripts_dir: ~/projects/research
 ```
 
-**Environment Override**: Set `NEXUS_CONFIG=/path/to/config.yaml` to use alternate config.
+**Environment Overrides**:
+- `NEXUS_CONFIG=/path/to/config.yaml` — use an alternate config file
+- `NEXUS_VAULT_SPEC=/path/to/vault-spec.yaml` — validate vault structure
+  against a custom PARA spec (falls back to bundled `nexus/data/vault-spec.yaml`)
 
 ## Adding New Commands
 
@@ -366,10 +372,10 @@ nexus learn getting-started  # Start learning
 ## Testing
 
 ```bash
-# Run all tests (422 tests)
+# Run all tests (499 tests)
 uv run pytest
 
-# Run with coverage (current: 75%)
+# Run with coverage (current: 76.81%)
 uv run pytest --cov=nexus
 
 # Run specific test file
@@ -441,7 +447,7 @@ echo $PATH | grep ".local/bin"
 
 ## Project Status
 
-### Completed Features (v0.5.0)
+### Completed Features (v0.5.2)
 ✅ Core CLI infrastructure (Typer, Rich)
 ✅ Research domain (Zotero, PDFs)
 ✅ Knowledge domain (Vault, search, graph)
@@ -452,12 +458,14 @@ echo $PATH | grep ".local/bin"
 ✅ Batch manuscript operations
 ✅ MCP server integration (17 tools)
 ✅ Comprehensive documentation (MkDocs)
-✅ Testing infrastructure (422 tests, 75% coverage)
+✅ Testing infrastructure (499 tests, 76.81% coverage)
 ✅ CI/CD (GitHub Actions, multi-platform)
+✅ Full type safety (0 mypy errors across 18 source files)
 
 ### Key Metrics
-- **Version**: 0.5.0
-- **Tests**: 422 passing (75% coverage)
+- **Version**: 0.6.1
+- **Tests**: 719 passing, 1 skipped (87.5% coverage)
+- **Mypy**: 0 errors across 20 source files
 - **Commands**: 50+ across 4 domains
 - **Documentation**: 9,500+ lines (MkDocs)
 - **Tutorial Steps**: 30 (interactive learning)
@@ -467,7 +475,7 @@ echo $PATH | grep ".local/bin"
 - **Main CLI**: `nexus/cli.py` (1,900+ lines)
 - **Tutorial System**: `nexus/utils/tutorial.py` (500+ lines)
 - **Config Management**: `nexus/utils/config.py`
-- **Tests**: `tests/` (422 tests)
+- **Tests**: `tests/` (499 tests)
 - **Docs**: `docs/` (MkDocs site)
 - **Tutorial Docs**: 
   - `TUTORIAL_GUIDE.md` (2,000 lines)
@@ -523,24 +531,32 @@ nexus doctor
 5. **Configuration required**: Many features need `~/.config/nexus/config.yaml`
 6. **Package name**: Install as `nexus-cli`, not `nexus` (name collision)
 
-## Recent Changes (v0.5.0)
+## Recent Changes
 
+### v0.5.2 (Jun 2, 2026)
+- ✅ Full type safety: 0 mypy errors across 18 source files (fixed 142)
+- ✅ `TYPE_CHECKING` imports + return type annotations on all `_get_*` helpers in `cli.py`
+- ✅ `dict[str, Any]` / `list[dict[str, Any]]` throughout domain modules
+
+### v0.5.1 (Dec 31, 2025)
+- ✅ Comprehensive Zotero testing (38 new tests, 96.89% coverage)
+- ✅ Tutorial system testing (39 new tests, 94.2% coverage)
+- ✅ 499 tests passing (76.81% coverage)
+
+### v0.5.0
 - ✅ Renamed `tutorial` command to `learn` (simpler)
-- ✅ Removed "run" action (direct execution)
-- ✅ Added interactive tutorial system (3 levels)
-- ✅ Added graph export formats
+- ✅ Added interactive tutorial system (3 levels, 30 steps)
+- ✅ Added graph export formats (GraphML, D3.js, JSON)
 - ✅ Added batch manuscript operations
-- ✅ Updated all documentation
 - ✅ MkDocs integration for tutorials
-- ✅ 422 tests passing (75% coverage)
 
-## Testing Strategy (Updated Dec 31, 2025)
+## Testing Strategy (Updated Jun 2, 2026)
 
 ### Current Test Coverage
 
 **Overall Statistics:**
-- **500 tests** (up from 422 in v0.5.0)
-- **76.65% coverage** (up from 75%)
+- **499 tests** passing, 1 skipped (76.81% coverage)
+- **0 mypy errors** across all 18 source files (fixed 142 in v0.5.2)
 - **High-quality modules** (90%+ coverage):
   - Zotero (96.89%) 🚀 - Research domain
   - Tutorial (94.2%) 🎓 - Utils domain

nexus_cli-0.6.1/ORCHESTRATE-nexus-enhancement.md

@@ -0,0 +1,174 @@
+# ORCHESTRATE: Nexus Enhancement Plan
+**Created:** 2026-06-02  
+**Worktree:** `~/.git-worktrees/nexus-cli/nexus-enhancement`  
+**Branch:** `feature/nexus-enhancement` → `dev` → `main`  
+**Specs:** `docs/specs/SPEC-*.md`
+
+---
+
+## Overview
+
+Four independent sessions improving nexus-cli quality and establishing
+the shared contract between `nexus/` (architecture) and `nexus-cli/` (tooling).
+
+Sessions 1–3 are parallel-safe (no shared files). Session 4 (nexus doctor)
+touches two repos — do it after the others are merged to avoid conflicts.
+
+---
+
+## Session 1: courses.py Coverage
+**Branch:** `feature/courses-coverage` off `dev`  
+**Spec:** `docs/specs/SPEC-courses-coverage.md`  
+**Worktree:** `~/.git-worktrees/nexus-cli/courses-coverage`  
+**Effort:** ~2.5 hours  
+**Goal:** `teaching/courses.py` 70% → 90%+, ≥30 tests, 0 mypy errors
+
+### Start this session:
+```bash
+cd /Users/dt/projects/dev-tools/nexus-cli
+git worktree add ~/.git-worktrees/nexus-cli/courses-coverage -b feature/courses-coverage dev
+cd ~/.git-worktrees/nexus-cli/courses-coverage
+claude
+```
+
+### Session prompt:
+> Working in nexus-cli. Read CLAUDE.md for conventions.
+> Read docs/specs/SPEC-courses-coverage.md — implement it exactly.
+> Follow the 5-phase blueprint (infrastructure → core tests → edge cases →
+> type safety → verification). Target: courses.py ≥90% coverage, ≥30 tests,
+> 0 mypy errors. Commit on feature/courses-coverage, then stop.
+
+### Done when:
+- [ ] `uv run --extra dev pytest tests/test_courses.py --cov=nexus/teaching/courses` shows ≥90%
+- [ ] 0 mypy errors: `uv run mypy nexus/teaching/courses.py`
+- [ ] Full suite: 499+ passed, 0 failed
+- [ ] Committed on `feature/courses-coverage`
+
+---
+
+## Session 2: bibliography.py Coverage
+**Branch:** `feature/bibliography-coverage` off `dev`  
+**Spec:** `docs/specs/SPEC-bibliography-coverage.md`  
+**Worktree:** `~/.git-worktrees/nexus-cli/bibliography-coverage`  
+**Effort:** ~2.5 hours  
+**Goal:** `writing/bibliography.py` 74% → 90%+, ≥30 tests, 0 mypy errors
+
+### Start this session:
+```bash
+cd /Users/dt/projects/dev-tools/nexus-cli
+git worktree add ~/.git-worktrees/nexus-cli/bibliography-coverage -b feature/bibliography-coverage dev
+cd ~/.git-worktrees/nexus-cli/bibliography-coverage
+claude
+```
+
+### Session prompt:
+> Working in nexus-cli. Read CLAUDE.md for conventions.
+> Read docs/specs/SPEC-bibliography-coverage.md — implement it exactly.
+> Follow the 5-phase blueprint. Target: bibliography.py ≥90% coverage,
+> ≥30 tests, 0 mypy errors. Commit on feature/bibliography-coverage, then stop.
+
+### Done when:
+- [ ] `uv run --extra dev pytest tests/test_bibliography.py --cov=nexus/writing/bibliography` shows ≥90%
+- [ ] 0 mypy errors: `uv run mypy nexus/writing/bibliography.py`
+- [ ] Full suite: 499+ passed, 0 failed
+- [ ] Committed on `feature/bibliography-coverage`
+
+---
+
+## Session 3: cli.py Coverage
+**Branch:** `feature/cli-coverage` off `dev`  
+**Spec:** `docs/specs/SPEC-cli-coverage.md`  
+**Worktree:** `~/.git-worktrees/nexus-cli/cli-coverage`  
+**Effort:** ~3 hours  
+**Goal:** `cli.py` 66% → 80%+, ≥35 new tests  
+**Note:** Do Sessions 1 and 2 first — warm-up before the largest file.
+
+### Start this session:
+```bash
+cd /Users/dt/projects/dev-tools/nexus-cli
+git worktree add ~/.git-worktrees/nexus-cli/cli-coverage -b feature/cli-coverage dev
+cd ~/.git-worktrees/nexus-cli/cli-coverage
+claude
+```
+
+### Session prompt:
+> Working in nexus-cli. Read CLAUDE.md for conventions.
+> Read docs/specs/SPEC-cli-coverage.md — implement it exactly.
+> Subcommand-by-subcommand approach. Target: cli.py ≥80% coverage,
+> ≥35 new tests. Commit on feature/cli-coverage, then stop.
+
+### Done when:
+- [ ] `uv run --extra dev pytest tests/test_cli*.py --cov=nexus/cli` shows ≥80%
+- [ ] Full suite: 499+ passed, 0 failed
+- [ ] Committed on `feature/cli-coverage`
+
+---
+
+## Session 4: nexus doctor (Cross-repo)
+**Branch:** `feature/nexus-doctor` off `nexus-cli/dev`  
+**Spec:** `docs/specs/SPEC-nexus-doctor.md`  
+**Worktree:** `~/.git-worktrees/nexus-cli/nexus-doctor`  
+**Also touches:** `nexus/` repo (docs commit to `dev`)  
+**Effort:** ~2 hours  
+**Prerequisite:** Sessions 1–3 merged to dev (avoid conflicts in cli.py)
+
+### Start this session:
+```bash
+cd /Users/dt/projects/dev-tools/nexus-cli
+git worktree add ~/.git-worktrees/nexus-cli/nexus-doctor -b feature/nexus-doctor dev
+cd ~/.git-worktrees/nexus-cli/nexus-doctor
+claude
+```
+
+### Session prompt:
+> Working in nexus-cli. Read CLAUDE.md for conventions.
+> Read docs/specs/SPEC-nexus-doctor.md — implement it exactly.
+> This spans two repos: (1) add vault-spec.yaml to nexus/ on dev,
+> (2) add nexus/utils/vault_spec.py and extend nexus doctor in nexus-cli.
+> Bundle a default vault-spec.yaml in nexus/data/. Add ≥10 tests.
+> Commit nexus-cli work on feature/nexus-doctor. Commit nexus/ work
+> directly on nexus/dev (docs only). Then stop.
+
+### Done when:
+- [ ] `nexus/vault-spec.yaml` committed to `nexus/dev`
+- [ ] `nexus/utils/vault_spec.py` created with tests
+- [ ] `nexus doctor` shows vault structure section
+- [ ] `nexus doctor --json` includes vault checks
+- [ ] ≥10 tests in `tests/test_vault_spec.py`
+- [ ] Committed on `feature/nexus-doctor`
+
+---
+
+## Integration Order
+
+```
+Session 1 (courses)  ─┐
+Session 2 (biblio)   ─┤─→ merge all to dev ─→ Session 4 (doctor)
+Session 3 (cli)      ─┘         ↑
+                          PR each feature/* → dev
+                          then release PR dev → main (v0.6.0)
+```
+
+Sessions 1–3 can run in any order or in parallel (separate worktrees,
+no shared files). Session 4 must come after all three are merged to dev.
+
+---
+
+## Release: v0.6.0
+
+After all four sessions merged to dev:
+```bash
+# From nexus-cli root on dev:
+# bump version 0.5.1 → 0.6.0
+# update CHANGELOG
+# PR dev → main
+# tag v0.6.0
+# update homebrew tap
+```
+
+Expected metrics at v0.6.0:
+- Overall coverage: 76% → ~82%+
+- courses.py: 70% → 90%+
+- bibliography.py: 74% → 90%+
+- cli.py: 66% → 80%+
+- nexus doctor: validates vault structure (shared contract live)

{nexus_cli-0.5.2 → nexus_cli-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nexus-cli
-Version: 0.5.2
+Version: 0.6.1
 Summary: Knowledge workflow CLI for research, teaching, and writing - Claude's body for academic work
 Project-URL: Homepage, https://github.com/Data-Wise/nexus-cli
 Project-URL: Documentation, https://data-wise.github.io/nexus-cli
@@ -165,7 +165,8 @@ nexus knowledge search "propensity score"
 
 | Command | Description |
 |---------|-------------|
-| `nexus doctor` | Check Nexus health and integrations |
+| `nexus help [topic]` | Flow-cli-style quick-start cheatsheet (main, research, teach, write, knowledge) |
+| `nexus doctor` | Check health + validate PARA vault structure (exits 1 if required folders missing) |
 | `nexus config` | View or edit configuration |
 | `nexus learn` | Interactive learning tutorials (getting-started, medium, advanced) |
 | `nexus --version` | Show version |

{nexus_cli-0.5.2 → nexus_cli-0.6.1}/README.md

@@ -124,7 +124,8 @@ nexus knowledge search "propensity score"
 
 | Command | Description |
 |---------|-------------|
-| `nexus doctor` | Check Nexus health and integrations |
+| `nexus help [topic]` | Flow-cli-style quick-start cheatsheet (main, research, teach, write, knowledge) |
+| `nexus doctor` | Check health + validate PARA vault structure (exits 1 if required folders missing) |
 | `nexus config` | View or edit configuration |
 | `nexus learn` | Interactive learning tutorials (getting-started, medium, advanced) |
 | `nexus --version` | Show version |

{nexus_cli-0.5.2 → nexus_cli-0.6.1}/TUTORIAL_GUIDE.md

@@ -1,5 +1,11 @@
 # Nexus Interactive Tutorial System
 
+> **TL;DR** (30 seconds)
+> - **What:** The built-in `nexus learn` tutorial system — 3 levels, 30 steps.
+> - **Why:** Learn the CLI hands-on at your own pace.
+> - **How:** `nexus learn` to browse, `nexus learn getting-started` to begin.
+> - **Next:** [Quick Reference →](tutorial-quick-ref.md)
+
 ## Overview
 
 Nexus includes a built-in interactive tutorial system to help new users learn the CLI at their own pace. Tutorials are organized into three levels:

{nexus_cli-0.5.2 → nexus_cli-0.6.1}/TUTORIAL_QUICK_REF.md

@@ -1,5 +1,11 @@
 # Nexus Tutorial Quick Reference
 
+> **TL;DR** (30 seconds)
+> - **What:** Cheat sheet for the `nexus learn` tutorial commands.
+> - **Why:** Fast lookup for starting, resuming, and listing tutorials.
+> - **How:** `nexus learn medium --step 5` resumes from step 5.
+> - **Next:** [Full Tutorial Guide →](tutorial-guide.md)
+
 ## Commands
 
 ```bash

nexus_cli-0.6.1/docs/adhd-quick-start.md

@@ -0,0 +1,56 @@
+# ⚡ ADHD Quick Start
+
+> Get Nexus working in **under 2 minutes**. No reading required.
+
+## ⏱️ First 30 Seconds
+
+The absolute essentials:
+
+```bash
+nexus doctor                 # Check everything is wired up
+nexus --version              # Confirm install (should show 0.6.1)
+nexus learn                  # See what you can learn
+```
+
+If `nexus doctor` shows green checks, you're ready.
+
+## ⏱️ Next 5 Minutes
+
+Once the basics work, pick one:
+
+- **🎓 Learn by doing:** `nexus learn getting-started` (7 steps, ~10 min)
+- **🔬 Search papers:** `nexus research zotero search "your topic" --json`
+- **🧠 Search everything:** `nexus knowledge search "your topic" --json`
+- **⚙️ Configure:** [Configuration guide](getting-started/configuration.md)
+
+## 🆘 Stuck? Run These
+
+Something not working? Try these in order:
+
+```bash
+nexus doctor                 # Diagnose config/data issues
+nexus --help                 # See all commands
+nexus <domain> --help        # e.g. nexus research --help
+```
+
+Most problems are a missing path in `~/.config/nexus/config.yaml`. Run `nexus doctor` — it tells you exactly what's missing.
+
+## 🎯 ADHD-Friendly Features
+
+This documentation is built for fast, scannable reading:
+
+- ⏱️ **Time estimates** on every tutorial
+- 📦 **TL;DR boxes** at the top of every page (30-second summaries)
+- 📊 **[Visual workflow diagrams](workflows/index.md)** for visual learners
+- ✅ **Quick wins first** — the one command you need, before the deep dive
+- 🚀 **Copy-paste commands** — no reconstruction required
+
+## 📚 Where to Go Next
+
+| I want to... | Go here |
+|---|---|
+| Install Nexus | [Installation](getting-started/installation.md) |
+| Learn step-by-step | [Interactive Tutorials](tutorials/tutorial-system.md) |
+| See the whole picture | [Visual Workflows](workflows/index.md) |
+| Look up a command | [CLI Reference](reference/cli.md) |
+| Understand the domains | [User Guide](guide/overview.md) |

{nexus_cli-0.5.2 → nexus_cli-0.6.1}/docs/changelog.md

@@ -1,3 +1,48 @@
+## [0.6.1] - 2026-06-03
+
+### Changed
+- **Test coverage**: `vault.py` raised from 78% → **98.14%** (+34 tests),
+  meeting the last outstanding v0.6.0 coverage target. New tests cover the
+  ripgrep search fallback (rg-missing, timeout, malformed JSON), `search_files`,
+  template loading/creation, daily notes, invalid-YAML frontmatter handling,
+  missing-vault guards, and the tag-graph node/edge paths.
+
+---
+
+## [0.6.0] - 2026-06-03
+
+### Added
+- **🩺 `nexus doctor` vault structure validation** — the health check now
+  validates your Obsidian vault against the PARA folder spec
+  (`00-INBOX`, `10-PROJECTS`, `20-AREAS`, `30-RESOURCES`, `40-ARCHIVE`)
+  - New `nexus/utils/vault_spec.py` — spec loader + `check_vault_structure()`
+  - Bundled default `nexus/data/vault-spec.yaml` (works without the `nexus/`
+    architecture repo installed)
+  - `NEXUS_VAULT_SPEC` env var to validate against a custom spec
+  - **Exit code**: `nexus doctor` now exits `1` when required PARA folders are
+    missing or the spec is invalid (exits `0` otherwise) — making it usable as
+    a scriptable/CI health gate. Optional-folder gaps are warnings only.
+  - First machine-readable contract between `nexus` (architecture) and
+    `nexus-cli` (tooling), preventing silent vault-structure drift
+  - Robust spec loading: clear errors for missing/empty/malformed YAML
+  - New tests for `vault_spec.py` (100% coverage) + CLI-level doctor tests
+- **🧭 `nexus help [topic]`** — flow-cli-style quick-start cheatsheets
+  (box header → most-common → quick examples → categorized actions → tips →
+  see-also). Topics: `main`, `research`, `teach`, `write`, `knowledge`.
+  Complements the exhaustive `--help`.
+
+### Changed
+- **Test coverage**: 76.81% → **87.5%** (+~340 tests across courses,
+  bibliography, cli, vault_spec, help_text via the v0.6.0 enhancement plan)
+- **CI**: workflows now trigger on the `dev` branch (previously `main`/`develop`
+  only, so PRs to `dev` received no CI)
+
+### Docs
+- New [Reference Card](reference/refcard.md); `nexus help` + vault validation
+  documented across CLI reference, configuration, and tutorials
+
+---
+
 ## [0.5.2] - 2026-06-02
 
 ### Fixed