@popoverai/dotrequirements 0.13.0 → 0.15.0

package/README.md

@@ -1,10 +1,21 @@
 # dot•requirements
 
-Requirements tracking CLI, test harness, and MCP server for AI-assisted development.
+**One source of truth for what your software should do.**
+Readable. Testable. AI-accessible.
 
-**dot•requirements** treats requirements as discrete, testable data that flows from discovery through implementation to testing. Write requirements as structured Markdown, reference them in tests, and track coverage over time.
+---
+
+Tests prove *something* works—but nobody is certain it's the right something. Requirements live scattered across docs, issue trackers, and people's heads. They drift out of sync with actual code. And AI assistants can't access them at all.
+
+**dot•requirements** closes this gap. Write requirements as structured Markdown, reference them directly in tests, and see coverage update automatically. When a requirement changes, the tests that validate it are one click away.
+
+> **Alpha Software** — Under active development. Please report issues to support@popover.ca.
+
+## Who Is This For?
 
-> **Alpha Software** — This package is under active development and may be unstable or incomplete. We're working toward a stable release, but things may break. Please report issues to support@popover.ca.
+- **Developers** who want tests that prove the right behavior, not just "80% coverage"
+- **Product managers** who want visibility into what's actually being tested
+- **AI-first builders** who want clear requirements for faster, more accurate implementations
 
 ## Installation
 
@@ -76,27 +87,6 @@ After running tests, you'll see a coverage report showing which requirements hav
 
 ---
 
-## What Works Locally
-
-The following features work fully offline—no account required:
-
-- Write requirements (`.requirements.md` files)
-- Validate requirements (`dotreq test`)
-- Reference requirements in tests (`requirement()`)
-- Coverage reporting (console output)
-- MCP tools (search, validate, explore)
-
-The following features require a dot•requirements cloud account:
-
-- Sync requirements (`pull` / `push`)
-- Historical coverage tracking
-- AI-powered style checking
-- Team collaboration
-
-To enable cloud features, run `dotreq login`.
-
----
-
 ## CLI Commands
 
 ### `dotreq init`
@@ -124,8 +114,19 @@ Sync requirements from dot•requirements cloud to local `.requirements/` files.
 dotreq pull
 dotreq pull --project <project-id>
 dotreq pull --document <document-id>
+dotreq pull --share <token>
+```
+
+**First-time setup with a share token:**
+
+If a team member shares a pull command with you, you can pull requirements without creating an account:
+
+```bash
+npx @popoverai/dotrequirements pull --share drt_abc123...
 ```
 
+This gives you read-only access to view requirements. To push changes or report coverage, run `dotreq link` afterward.
+
 ### `dotreq push`
 
 Push local requirements to dot•requirements cloud.
@@ -145,15 +146,6 @@ dotreq test
 dotreq test --file .requirements/auth.requirements.md
 ```
 
-### `dotreq login` / `logout`
-
-Authenticate with dot•requirements cloud.
-
-```bash
-dotreq login
-dotreq logout
-```
-
 ### `dotreq mcp-setup`
 
 Configure the MCP server for AI assistants (Claude Code, Cursor, etc.).
@@ -172,9 +164,30 @@ dotreq mcp
 
 ---
 
+## What Works Locally
+
+The following features work fully offline—no account required:
+
+- Write requirements (`.requirements.md` files)
+- Validate requirements (`dotreq test`)
+- Reference requirements in tests (`requirement()`)
+- Coverage reporting (console output)
+- MCP tools (search, validate, explore)
+
+The following features require a dot•requirements cloud account:
+
+- Sync requirements (`pull` / `push`)
+- Historical coverage tracking
+- AI-powered style checking
+- Team collaboration
+
+To enable cloud features, run `dotreq link` to connect your project to the cloud.
+
+---
+
 ## Test Harness
 
-The test harness tracks which requirements are exercised by your tests.
+Stop wondering "did we test that?" The test harness tracks which requirements are exercised by your tests and shows gaps instantly.
 
 ### Setup with Vitest
 
@@ -290,6 +303,8 @@ test(requirement('AUTH-LOGIN-1', 'AUTH-SECURITY-1'), () => {
 
 ### Coverage Reporting
 
+Coverage isn't just a number—it's a map of which features have been tested and which haven't.
+
 #### Local Report
 
 After tests complete, a coverage summary prints to the console:
@@ -321,12 +336,7 @@ With cloud credentials configured, coverage is automatically reported to dot•r
 - Branch-based coverage (tracks `main`, feature branches, etc.)
 - Query coverage via the MCP server
 
-Configure by adding to `.env.local`:
-
-```bash
-DOTREQUIREMENTS_PROJECT_ID=your-project-id
-DOTREQUIREMENTS_PROJECT_SECRET=your-project-secret
-```
+Run `dotreq link` to connect your project to the cloud and enable coverage reporting.
 
 Cloud reporting is fire-and-forget—it never blocks or fails your tests.
 
@@ -399,7 +409,7 @@ See [MARKDOWN_SCHEMA.md](https://github.com/PopoverAI/dotrequirements/blob/main/
 
 ## MCP Server
 
-The package includes an MCP (Model Context Protocol) server for AI assistant integration. This enables AI coding assistants to search, validate, and work with your requirements.
+AI assistants can read your requirements in context, draft new ones, and verify tests actually validate what they claim to. The MCP server makes this possible through a standard protocol that works with Claude Code, Cursor, and other AI coding assistants.
 
 ### Setup
 
@@ -422,7 +432,7 @@ Follow the prompts to configure for your AI assistant (Claude Code, Cursor, etc.
 **Authoring:**
 - `create_requirement_document` — Get a Markdown template with format examples
 - `validate_requirements` — Validate file schema (works offline)
-- `style_check` — AI-powered style feedback on requirements
+- `style_check` — AI-powered style feedback on requirements (supports optional `requirementKeys` filter)
 - `review_test` — Comprehensive test review (style + semantic correctness)
 
 **Cloud:**
@@ -433,6 +443,39 @@ Follow the prompts to configure for your AI assistant (Claude Code, Cursor, etc.
 **Diagnostic:**
 - `debug_mcp_environment` — Debug MCP server configuration
 
+### CI/CD Mode
+
+For CI/CD environments (GitHub Actions, etc.), use the `--auth-from-env` flag to read credentials from environment variables instead of `project-settings.json`:
+
+```bash
+node packages/cli/dist/mcp/index.js --auth-from-env
+```
+
+Required environment variables:
+- `DOTREQ_PROJECT_ID` — Your project slug
+- `DOTREQ_PROJECT_SECRET` — Your project secret
+
+**Important:** Without `--auth-from-env`, these environment variables are ignored. This explicit opt-in prevents credential conflicts between local and CI environments.
+
+Example MCP config for GitHub Actions:
+
+```json
+{
+  "mcpServers": {
+    "dotrequirements": {
+      "command": "node",
+      "args": ["packages/cli/dist/mcp/index.js", "--auth-from-env"],
+      "env": {
+        "DOTREQ_PROJECT_ID": "${DOTREQ_PROJECT_ID}",
+        "DOTREQ_PROJECT_SECRET": "${DOTREQ_PROJECT_SECRET}"
+      }
+    }
+  }
+}
+```
+
+See the [CI/CD Integration docs](https://dotrequirements.io/tools/ai/ci-cd) for complete examples.
+
 ---
 
 ## Package Exports
@@ -458,15 +501,16 @@ import '@popoverai/dotrequirements/mcp';
 
 ## Configuration
 
-The CLI stores configuration in `.env.local`:
+The CLI stores project credentials in `.requirements/project-settings.json`:
 
-```bash
-# Project credentials (from dotreq init or login)
-DOTREQUIREMENTS_PROJECT_ID=your-project-id
-DOTREQUIREMENTS_PROJECT_SECRET=your-project-secret
+```json
+{
+  "projectId": "your-project-id",
+  "projectSecret": "your-project-secret"
+}
 ```
 
-The `.env.local` file is automatically added to `.gitignore` during initialization.
+This file is automatically added to `.gitignore` during initialization.
 
 ---
 

package/dist/cli.js

@@ -7,8 +7,6 @@ import { pushCommand } from './commands/push.js';
 import { testCommand } from './commands/test.js';
 import { mcpCommand } from './commands/mcp.js';
 import { mcpSetupCommand } from './commands/mcp-setup.js';
-import { loginCommand } from './commands/login.js';
-import { logoutCommand } from './commands/logout.js';
 import { loadEnvFile } from './utils/env.js';
 import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
@@ -59,6 +57,7 @@ program
     .description('Sync requirements from cloud to local .requirements/ files')
     .option('-p, --project <id>', 'Project ID to sync')
     .option('-d, --document <id>', 'Specific document ID to sync')
+    .option('-s, --share <token>', 'Read-only share token for quick onboarding (no setup required)')
     .action(wrapCommand(pullCommand));
 program
     .command('push [file]')
@@ -78,13 +77,5 @@ program
     .command('mcp-setup')
     .description('Configure MCP server for your AI assistant (Claude Code, Claude Desktop, etc.)')
     .action(wrapCommand(mcpSetupCommand));
-program
-    .command('login')
-    .description('Authenticate with dot•requirements and enable cloud features')
-    .action(wrapCommand(loginCommand));
-program
-    .command('logout')
-    .description('Clear stored authentication tokens')
-    .action(wrapCommand(logoutCommand));
 program.parse();
 //# sourceMappingURL=cli.js.map