@popoverai/dotrequirements 0.13.0 → 0.15.0

package/dist/commands/link.js

@@ -1,74 +1,81 @@
-import * as fs from 'fs';
-import * as path from 'path';
-import { promptConfirm } from '../utils/prompts.js';
+import { promptConfirm, promptChoice } from '../utils/prompts.js';
 import { pullCommand } from './pull.js';
-import { hasValidTokens, getTokens } from '../utils/token-storage.js';
 import { executeOAuthFlow } from '../utils/oauth-flow.js';
 import { ConvexHttpClient } from 'convex/browser';
 import { getConvexUrl } from '../config.js';
 import { brand } from '../utils/brand.js';
-import { selectTeam, selectProject, getOrCreateProjectSecret } from '../utils/project-selector.js';
+import { selectTeam, selectProject, getOrCreateProjectSecret, promptExpiryDays } from '../utils/project-selector.js';
+import { findProjectRoot, readProjectSettings, writeProjectSettings, } from '../utils/project-settings.js';
 /**
- * Link command - connect local environment to an existing project.
+ * Link command - connect or reconnect local project to cloud.
  *
- * Flow:
- * 1. Check authentication (prompt to login if not)
- * 2. Fetch user's teams with usage info
- * 3. Let user select a team
- * 4. Fetch projects for that team
- * 5. Let user select a project
- * 6. Get or create user's secret for that project
- * 7. Write credentials to .env.local
- * 8. Optionally pull requirements
+ * Requirements:
+ * - LINK-1: Requires existing .requirements/ folder
+ * - LINK-2: Offers refresh when credentials exist
+ * - LINK-3: Uses inline OAuth (no persistent tokens)
+ * - LINK-4, LINK-5: Team and project selection
+ * - LINK-6: Saves credentials to project-settings.json
+ * - LINK-7: Optionally pulls requirements
+ * - LINK-8: Handles network errors gracefully
  */
 export async function linkCommand() {
     try {
-        console.log(`Linking to existing ${brand} project...\n`);
+        console.log(`Linking to ${brand} cloud...\n`);
         const cwd = process.cwd();
-        const envPath = path.join(cwd, '.env.local');
-        // 1. Check authentication
-        let isAuthenticated = await hasValidTokens();
-        if (!isAuthenticated) {
-            const shouldLogin = await promptConfirm('You need to authenticate to link to a project. Log in now?', true);
-            if (!shouldLogin) {
-                console.log('Aborted.');
-                return;
-            }
-            try {
-                console.log();
-                await executeOAuthFlow();
-                console.log();
-                isAuthenticated = true;
-            }
-            catch (error) {
-                console.error('\nAuthentication failed:', error instanceof Error ? error.message : String(error));
-                console.log('Please try running "dotrequirements login" separately.\n');
+        // LINK-1: Check if .requirements/ folder exists
+        const projectRoot = findProjectRoot(cwd);
+        if (!projectRoot || projectRoot !== cwd) {
+            console.log('No .requirements/ folder found.');
+            console.log('Run "dotrequirements init" to initialize a project first.\n');
+            return;
+        }
+        // LINK-2: Check for existing credentials and offer refresh
+        let existingCredentials;
+        try {
+            existingCredentials = readProjectSettings(projectRoot);
+        }
+        catch {
+            // Invalid settings - treat as no credentials
+            existingCredentials = undefined;
+        }
+        if (existingCredentials) {
+            const shouldContinue = await handleExistingCredentials(existingCredentials);
+            if (!shouldContinue) {
                 return;
             }
         }
-        // 2. Set up authenticated client
-        const tokens = await getTokens();
-        if (!tokens) {
-            throw new Error('Authentication tokens not found');
+        // LINK-3: Inline OAuth (no persistent tokens)
+        let oauthResult;
+        try {
+            oauthResult = await executeOAuthFlow();
+            console.log();
+        }
+        catch (error) {
+            console.error('\nAuthentication failed:', error instanceof Error ? error.message : String(error));
+            console.log('Please try again later.\n');
+            return;
         }
+        // Set up authenticated client using the session token
         const client = new ConvexHttpClient(getConvexUrl());
-        client.setAuth(tokens.accessToken);
-        // 3. Select team
-        const selectedTeamId = await selectTeam(client);
-        if (!selectedTeamId) {
-            console.log('Aborted.');
+        client.setAuth(oauthResult.accessToken);
+        // LINK-4: Select team
+        const selectedTeam = await selectTeam(client);
+        if (!selectedTeam) {
+            console.log('Link cancelled.');
             return;
         }
-        // 4. Select project
-        const selectedProject = await selectProject(client, selectedTeamId);
+        // LINK-5: Select project
+        const selectedProject = await selectProject(client, selectedTeam.teamId);
         if (!selectedProject) {
-            console.log('Aborted.');
+            // selectProject already shows message about no projects
             return;
         }
-        // 5. Get or create secret for this project
+        // AUTHZ-3: Prompt for secret expiry (paid tier only)
+        const expiryDays = await promptExpiryDays(selectedTeam.tier);
+        // LINK-5.3: Get or create secret for this project
         console.log('\nGetting project credentials...');
-        const secretResult = await getOrCreateProjectSecret(client, selectedProject.projectId);
-        const projectSlug = selectedProject.projectSlug || selectedProject.projectId;
+        const secretResult = await getOrCreateProjectSecret(client, selectedProject.projectId, expiryDays);
+        const projectId = selectedProject.projectSlug || selectedProject.projectId;
         const secret = secretResult.secret;
         if (secretResult.created) {
             console.log('✓ Created new project secret');
@@ -76,23 +83,23 @@ export async function linkCommand() {
         else {
             console.log('✓ Retrieved existing project secret');
         }
-        // 6. Write .env.local
-        const shouldContinue = await writeEnvFile(envPath, projectSlug, secret);
-        if (!shouldContinue) {
-            return;
-        }
-        // 7. Optionally pull requirements
+        // LINK-6: Write credentials to project-settings.json
+        writeProjectSettings(projectRoot, { projectId, projectSecret: secret });
+        console.log('✓ Wrote credentials to .requirements/project-settings.json');
+        // LINK-7: Optionally pull requirements
         const shouldPull = await promptConfirm('Pull requirements from cloud now?', true);
         if (shouldPull) {
             console.log('\nPulling requirements...');
-            await pullCommand({ project: projectSlug });
+            await pullCommand({ project: projectId });
         }
+        // LINK-7.2: Success message
         console.log(`\n✓ Successfully linked to project: ${selectedProject.projectName}`);
-        console.log(`  Project ID: ${projectSlug}`);
+        console.log(`  Project ID: ${projectId}`);
         console.log('\nDocumentation: https://docs.dotrequirements.io/getting-started');
     }
     catch (error) {
         console.error(`\n✗ Error: ${error instanceof Error ? error.message : String(error)}`);
+        // LINK-8: Network error guidance
         if (error instanceof Error && error.message.includes('fetch')) {
             console.error('\nCheck your internet connection and try again.');
             console.error('If the problem persists, visit https://status.convex.dev');
@@ -101,56 +108,24 @@ export async function linkCommand() {
     }
 }
 /**
- * Write .env.local file with confirmation if it already exists
- * Returns true if credentials were written or user chose to continue
- * Returns false if user aborted
+ * LINK-2: Handle existing credentials - offer refresh or connect to different project
+ * Returns true if user wants to continue (either refresh or different project)
+ * Returns false if user cancels
  */
-async function writeEnvFile(envPath, projectId, secret) {
-    const newEnvLines = [
-        '# dot•requirements configuration',
-        `DOTREQUIREMENTS_PROJECT_ID=${projectId}`,
-        `DOTREQUIREMENTS_PROJECT_SECRET=${secret}`,
-    ];
-    if (fs.existsSync(envPath)) {
-        const existingContent = fs.readFileSync(envPath, 'utf-8');
-        const hasProjectId = existingContent.includes('DOTREQUIREMENTS_PROJECT_ID');
-        const hasProjectSecret = existingContent.includes('DOTREQUIREMENTS_PROJECT_SECRET');
-        if (hasProjectId || hasProjectSecret) {
-            const shouldUpdate = await promptConfirm(`.env.local already contains ${brand} configuration. Update it?`, true);
-            if (!shouldUpdate) {
-                console.log('Aborted.');
-                return false;
-            }
-            // Remove old dotrequirements lines
-            const lines = existingContent.split('\n');
-            const filteredLines = lines.filter(line => !line.includes('DOTREQUIREMENTS_PROJECT_ID') &&
-                !line.includes('DOTREQUIREMENTS_PROJECT_SECRET') &&
-                !(line.trim() === '# dotrequirements configuration') &&
-                !(line.trim() === '# dot•requirements configuration'));
-            const updatedContent = filteredLines.join('\n').trimEnd() + '\n\n' + newEnvLines.join('\n') + '\n';
-            fs.writeFileSync(envPath, updatedContent);
-            console.log(`✓ Updated ${brand} configuration in .env.local`);
-            return true;
-        }
-        else {
-            const shouldAppend = await promptConfirm(`.env.local already exists. Add ${brand} configuration to it?`, true);
-            if (!shouldAppend) {
-                console.log('\nSkipped writing to .env.local. Please add these values manually:');
-                console.log(`  DOTREQUIREMENTS_PROJECT_ID=${projectId}`);
-                console.log(`  DOTREQUIREMENTS_PROJECT_SECRET=${secret}\n`);
-                return true;
-            }
-            const appendContent = '\n' + newEnvLines.join('\n') + '\n';
-            fs.appendFileSync(envPath, appendContent);
-            console.log(`✓ Added ${brand} configuration to .env.local`);
-            return true;
-        }
-    }
-    else {
-        const envContent = newEnvLines.join('\n') + '\n';
-        fs.writeFileSync(envPath, envContent);
-        console.log('✓ Wrote configuration to .env.local');
-        return true;
+async function handleExistingCredentials(credentials) {
+    console.log(`Currently linked to: ${credentials.projectId}\n`);
+    const choice = await promptChoice('What would you like to do?', [
+        { title: 'Refresh credentials for this project', value: 'refresh' },
+        { title: 'Connect to a different project', value: 'different' },
+    ]);
+    if (!choice) {
+        console.log('Link cancelled.');
+        return false;
     }
+    // Both options continue with OAuth flow
+    // For 'refresh', we'll match on the same project after team/project selection
+    // For 'different', user selects any project
+    // The flow is the same - user authenticates and selects team/project
+    return true;
 }
 //# sourceMappingURL=link.js.map

package/dist/commands/mcp-setup.js

@@ -1,98 +1,71 @@
 import { execSync } from 'child_process';
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
 import { homedir } from 'os';
-import { join, dirname } from 'path';
+import { join } from 'path';
 import prompts from 'prompts';
-import { findUp } from 'find-up';
-import { loadPlatformTemplate, loadTestWritingTemplate, loadOverviewTemplate } from '../utils/templates.js';
+import { loadTemplate } from '../utils/templates.js';
 import { brand } from '../utils/brand.js';
+import { getContextFileName, getContextFilePath, findDotrequirementsSection, appendOrUpdateSection, } from '../utils/context-file.js';
 /**
- * Platform-specific skills directory paths (relative to git root)
+ * Load the context file section template
  */
-const PLATFORM_SKILLS_DIRS = {
-    'claude-code': '.claude/skills',
-    'cursor': '.cursor/skills',
-    'antigravity': '.agent/skills',
-    'codex': '.codex/skills',
-    'github-copilot': '.github/skills',
-};
-/**
- * Load skill content by name
- */
-function loadSkillContent(skillName) {
-    switch (skillName) {
-        case 'dotreq-requirements':
-            return loadPlatformTemplate('claude-code-skill.md');
-        case 'dotreq-tests':
-            return loadTestWritingTemplate('claude-code-test-skill.md');
-        case 'dotreq-overview':
-            return loadOverviewTemplate('claude-code-overview-skill.md');
-    }
+function loadContextFileSection() {
+    return loadTemplate('context-file-section.md');
 }
 /**
- * Install a single skill to the specified base directory
+ * Install workflow guidance to the appropriate context file for a platform
  */
-async function installSkill(skillName, baseDir, gitRoot) {
-    const content = loadSkillContent(skillName);
-    const skillDir = join(gitRoot, baseDir, skillName);
-    const skillPath = join(skillDir, 'SKILL.md');
-    if (!existsSync(skillDir)) {
-        mkdirSync(skillDir, { recursive: true });
+async function installContextFileSection(platform) {
+    const contextFilePath = await getContextFilePath(platform);
+    if (!contextFilePath) {
+        console.error(`\n❌ Could not determine context file path for ${platform}`);
+        return;
     }
-    writeFileSync(skillPath, content, 'utf-8');
-    console.log(`   Created: ${skillPath}`);
-}
-/**
- * Prompt user to install workflow guidance
- */
-async function promptForGuidanceInstall(installPath) {
+    const fileName = getContextFileName(platform);
+    const sectionContent = loadContextFileSection();
+    // Check if file exists and has existing section
+    let existingSection = null;
+    if (existsSync(contextFilePath)) {
+        const content = readFileSync(contextFilePath, 'utf-8');
+        const section = findDotrequirementsSection(content);
+        if (section) {
+            existingSection = section.content;
+        }
+    }
+    // Prompt user
+    const action = existingSection ? 'Update' : existsSync(contextFilePath) ? 'Add to' : 'Create';
     const response = await prompts({
         type: 'confirm',
         name: 'install',
-        message: `Install workflow guidance? (recommended)\n  → ${installPath}`,
+        message: `${action} ${fileName} with dotrequirements workflow guidance?`,
         initial: true,
     });
-    return response.install ?? false;
-}
-/**
- * Install all three skills to a platform's skills directory
- */
-async function installAllSkills(platform, customPath) {
-    const gitDir = await findUp('.git', { type: 'directory' });
-    if (!gitDir) {
-        console.error('\n❌ Could not find git root directory.');
-        console.log('   Make sure you are inside a git repository.');
+    if (!response.install) {
+        console.log('');
         return;
     }
-    const gitRoot = dirname(gitDir);
-    const baseDir = customPath || PLATFORM_SKILLS_DIRS[platform];
-    if (!baseDir) {
-        console.error(`\n❌ Unknown platform: ${platform}`);
-        return;
-    }
-    // Prompt for each skill
-    const skills = [
-        { name: 'dotreq-overview', label: 'Overview' },
-        { name: 'dotreq-requirements', label: 'Requirements capture' },
-        { name: 'dotreq-tests', label: 'Test writing' },
-    ];
-    for (const skill of skills) {
-        const skillPath = join(gitRoot, baseDir, skill.name, 'SKILL.md');
-        const shouldInstall = await promptForGuidanceInstall(skillPath);
-        if (shouldInstall) {
-            try {
-                await installSkill(skill.name, baseDir, gitRoot);
-                console.log(`✅ ${skill.label} guidance installed\n`);
-            }
-            catch (error) {
-                console.error(`❌ Failed to install ${skill.label} guidance`);
-                console.log(`   Error: ${error instanceof Error ? error.message : String(error)}\n`);
-            }
-        }
-        else {
-            console.log('');
+    // If updating, show what will change
+    if (existingSection) {
+        const confirmUpdate = await prompts({
+            type: 'confirm',
+            name: 'confirm',
+            message: 'Existing dotrequirements section found. Replace it?',
+            initial: true,
+        });
+        if (!confirmUpdate.confirm) {
+            console.log('   Skipped.\n');
+            return;
         }
     }
+    try {
+        const result = appendOrUpdateSection(contextFilePath, sectionContent);
+        const actionVerb = result.action === 'created' ? 'Created' : result.action === 'appended' ? 'Added to' : 'Updated';
+        console.log(`✅ ${actionVerb} ${contextFilePath}\n`);
+    }
+    catch (error) {
+        console.error(`❌ Failed to update ${fileName}`);
+        console.log(`   Error: ${error instanceof Error ? error.message : String(error)}\n`);
+    }
 }
 /**
  * MCP setup command - configures the MCP server for AI assistants
@@ -175,7 +148,7 @@ async function setupClaudeCode() {
     if (mcpConfigured) {
         console.log('\n⚠️  Important: Restart Claude Code for changes to take effect.');
         console.log('\nYou can now ask your AI assistant to help write requirements!\n');
-        await installAllSkills('claude-code');
+        await installContextFileSection('claude-code');
     }
 }
 async function setupClaudeDesktop() {
@@ -285,7 +258,7 @@ async function setupCursor() {
         console.log(`   Config file: ${configPath}\n`);
         console.log('⚠️  Important: Reload or restart Cursor for changes to take effect.');
         console.log('\nYou can now ask your AI assistant to help write requirements!\n');
-        await installAllSkills('cursor');
+        await installContextFileSection('cursor');
     }
     catch (error) {
         console.error('❌ Failed to configure MCP automatically.');
@@ -379,7 +352,7 @@ async function setupAntigravity() {
         else {
             console.log('');
         }
-        await installAllSkills('antigravity');
+        await installContextFileSection('antigravity');
     }
     catch (error) {
         console.error('❌ Failed to configure MCP automatically.');
@@ -396,7 +369,7 @@ async function setupCodex() {
         console.log('\n✅ MCP configured successfully for Codex!');
         console.log('\n⚠️  Important: Restart Codex for changes to take effect.');
         console.log('\nYou can now ask your AI assistant to help write requirements!\n');
-        await installAllSkills('codex');
+        await installContextFileSection('codex');
     }
     catch (error) {
         console.error('\n❌ Failed to configure MCP automatically.');
@@ -413,24 +386,27 @@ async function setupGitHubCopilot() {
     console.log('ℹ️  GitHub Copilot discovers MCP servers from your IDE configuration.');
     console.log('   Please configure the MCP server in VS Code settings or GitHub settings.\n');
     console.log('   MCP server command: npx -y @popoverai/dotrequirements mcp\n');
-    await installAllSkills('github-copilot');
+    await installContextFileSection('github-copilot');
 }
 async function setupOther() {
-    console.log('\n📦 Custom Agent Skills Setup\n');
-    console.log('ℹ️  Agent Skills are installed as SKILL.md files in a skills directory.');
-    console.log('   Common locations:');
-    console.log('   - .claude/skills/  (Claude Code)');
-    console.log('   - .cursor/skills/  (Cursor)');
-    console.log('   - .agent/skills/   (Antigravity)');
-    console.log('   - .codex/skills/   (Codex)');
-    console.log('   - .github/skills/  (GitHub Copilot)\n');
+    console.log('\n📦 Custom Context File Setup\n');
+    console.log('ℹ️  Workflow guidance is added to a context file at your project root.');
+    console.log('   Common file names by platform:');
+    console.log('   - CLAUDE.md   (Claude Code)');
+    console.log('   - AGENTS.md   (Cursor, Codex, GitHub Copilot)');
+    console.log('   - GEMINI.md   (Antigravity)\n');
     const response = await prompts({
-        type: 'text',
-        name: 'path',
-        message: 'Enter the skills directory path (relative to git root):',
-        initial: '.skills',
+        type: 'select',
+        name: 'file',
+        message: 'Which context file should we update?',
+        choices: [
+            { title: 'AGENTS.md (most compatible)', value: 'AGENTS.md' },
+            { title: 'CLAUDE.md', value: 'CLAUDE.md' },
+            { title: 'GEMINI.md', value: 'GEMINI.md' },
+        ],
+        initial: 0,
     });
-    if (!response.path) {
+    if (!response.file) {
         console.log('\nSetup cancelled.');
         return;
     }
@@ -438,6 +414,13 @@ async function setupOther() {
     console.log('Configure your AI assistant to run the MCP server:');
     console.log('   Command: npx');
     console.log('   Args: -y @popoverai/dotrequirements mcp\n');
-    await installAllSkills('other', response.path);
+    // Determine platform based on file choice for the install function
+    const platformMap = {
+        'CLAUDE.md': 'claude-code',
+        'AGENTS.md': 'cursor', // Any AGENTS.md platform works
+        'GEMINI.md': 'antigravity',
+    };
+    const platform = platformMap[response.file];
+    await installContextFileSection(platform);
 }
 //# sourceMappingURL=mcp-setup.js.map

package/dist/commands/pull.d.ts

@@ -1,6 +1,7 @@
 interface PullOptions {
     project?: string;
     document?: string;
+    share?: string;
 }
 export declare function pullCommand(options: PullOptions): Promise<void>;
 export {};

package/dist/commands/pull.js

@@ -4,64 +4,80 @@ import { ConvexHttpClient } from 'convex/browser';
 import { getConvexUrl } from '../config.js';
 import { buildRequirementsFile } from '../schema/index.js';
 import { api } from '../convex.js';
-import { isLocalOnlyProject, CLOUD_FEATURES_REQUIRE_AUTH_MESSAGE } from '../utils/local-project.js';
 import { brand } from '../utils/brand.js';
 import { findRequirementsFiles } from '../mcp/requirements.js';
+import { getProjectCredentials } from '../utils/project-settings.js';
 export async function pullCommand(options) {
     try {
-        console.log(`Syncing requirements from ${brand} cloud...`);
         // Connect to Convex
         const convexUrl = getConvexUrl();
         const client = new ConvexHttpClient(convexUrl);
-        // Determine project ID
-        let projectId = options.project;
-        // If no project flag provided, try to read from .env.local
-        if (!projectId && !options.document) {
-            projectId = loadProjectIdFromEnv();
-            if (!projectId) {
-                throw new Error('Project ID not found. Either:\n' +
-                    '  1. Run "dotreq init" to initialize the project, or\n' +
-                    '  2. Use --project flag to specify the project ID');
+        let documents;
+        let projectName;
+        let isShareTokenFlow = false;
+        // SHARE-TOKEN-CLI-1: Handle share token flow (no project config needed)
+        if (options.share) {
+            isShareTokenFlow = true;
+            console.log(`Pulling requirements with share token...`);
+            try {
+                // SHARE-TOKEN-CLI-1.1: Pass only projectSecret, no projectSlug
+                // The authzQueryReadOnly wrapper will resolve project from the token
+                const result = await client.query(api.documents.queries.exportProjectForCli, {
+                    projectAuth: {
+                        projectSecret: options.share,
+                    },
+                });
+                documents = result.documents;
+                projectName = result.projectName;
+                // SHARE-TOKEN-CLI-1.2: Display project name in output
+                console.log(`\nProject: "${projectName}"`);
             }
-            // AUTHZ-2.0: Check if project is local-only
-            if (isLocalOnlyProject(projectId)) {
-                throw new Error(CLOUD_FEATURES_REQUIRE_AUTH_MESSAGE);
+            catch (error) {
+                // SHARE-TOKEN-CLI-2: Handle invalid/revoked tokens gracefully
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                if (errorMessage.includes('Invalid share token')) {
+                    throw new Error('Invalid share token. The token may be incorrect or has been revoked.\n' +
+                        'Please request a new share token from your team.');
+                }
+                throw error;
             }
         }
-        // Load project secret for authentication
-        const projectSecret = process.env.DOTREQUIREMENTS_PROJECT_SECRET;
-        if (!projectSecret) {
-            throw new Error('DOTREQUIREMENTS_PROJECT_SECRET not found. Either:\n' +
-                '  1. Run "dotrequirements init" or "dotrequirements login" to set up authentication, or\n' +
-                '  2. Set DOTREQUIREMENTS_PROJECT_SECRET in .env.local');
-        }
-        // Fetch documents
-        let documents;
-        if (options.document) {
-            // Fetch specific document
-            const doc = await client.query(api.documents.queries.exportForCli, {
-                projectAuth: {
-                    projectSlug: projectId,
-                    projectSecret,
-                },
-                target: { type: 'document', id: options.document },
-                documentId: options.document,
-            });
-            documents = doc ? [doc] : [];
-        }
-        else if (projectId) {
-            // Fetch all documents for project
-            // SYNC-ARCH-3.1: Use projectSlug (not projectId) since env stores the slug
-            documents = await client.query(api.documents.queries.exportProjectForCli, {
-                projectAuth: {
-                    projectSlug: projectId,
-                    projectSecret,
-                },
-                target: { type: 'project', slug: projectId },
-            });
-        }
         else {
-            throw new Error('Either --project or --document must be specified');
+            console.log(`Syncing requirements from ${brand} cloud...`);
+            // Get project credentials from .requirements/project-settings.json
+            // This throws helpful errors if project not found or not connected to cloud
+            const credentials = getProjectCredentials();
+            // Allow --project flag to override, but still need secret from settings
+            const projectId = options.project ?? credentials.projectId;
+            const projectSecret = credentials.projectSecret;
+            // Fetch documents
+            if (options.document) {
+                // Fetch specific document
+                const doc = await client.query(api.documents.queries.exportForCli, {
+                    projectAuth: {
+                        projectSlug: projectId,
+                        projectSecret,
+                    },
+                    target: { type: 'document', id: options.document },
+                    documentId: options.document,
+                });
+                documents = doc ? [doc] : [];
+            }
+            else if (projectId) {
+                // Fetch all documents for project
+                // SYNC-ARCH-3.1: Use projectSlug (not projectId) since env stores the slug
+                const result = await client.query(api.documents.queries.exportProjectForCli, {
+                    projectAuth: {
+                        projectSlug: projectId,
+                        projectSecret,
+                    },
+                });
+                documents = result.documents;
+                projectName = result.projectName;
+            }
+            else {
+                throw new Error('Either --project or --document must be specified');
+            }
         }
         if (documents.length === 0) {
             console.log('No documents found.');
@@ -98,6 +114,13 @@ export async function pullCommand(options) {
             console.log(`✓ Synced: ${fileName} (version ${doc.version})`);
         }
         console.log(`\nSuccessfully synced ${documents.length} document(s) to .requirements/`);
+        // SHARE-TOKEN-CLI-3: Show next steps for share token users
+        if (isShareTokenFlow) {
+            console.log('\n─────────────────────────────────────────────────────────');
+            console.log('Next steps to get full access (push, coverage):');
+            console.log('  Run: dotrequirements link');
+            console.log('─────────────────────────────────────────────────────────');
+        }
     }
     catch (error) {
         // Re-throw to let the CLI error handler display it cleanly
@@ -113,12 +136,6 @@ function sanitizeFileName(title) {
         .replace(/[^a-z0-9]+/g, '-')
         .replace(/^-+|-+$/g, '');
 }
-/**
- * Load project ID from process.env (already loaded from .env.local by CLI)
- */
-function loadProjectIdFromEnv() {
-    return process.env.DOTREQUIREMENTS_PROJECT_ID;
-}
 /**
  * Build an index mapping document IDs to their file paths.
  * Scans existing .requirements.md files across the entire workspace and extracts document.id from frontmatter.