sidecar-cli 0.1.3 → 0.1.4-beta.2

package/README.md

@@ -6,6 +6,8 @@ project memory for your work
 
 Sidecar is a local-first, CLI-first project memory and recording tool for human developers and AI coding agents.
 
+Documentation website: [usesidecar.dev](https://usesidecar.dev/)
+
 ## Why Sidecar exists
 
 - Keep project memory structured and local.
@@ -85,12 +87,41 @@ npm run dev -- --help
 
 ## Quick start
 
-Initialize in a project directory:
+1. Initialize in a project directory:
 
 ```bash
 sidecar init
 ```
 
+2. (Optional) Define shared instruction templates once:
+
+```bash
+mkdir -p ~/.sidecar-cli/instructions
+```
+
+Create template files such as:
+
+- `~/.sidecar-cli/instructions/web-app.md`
+- `~/.sidecar-cli/instructions/desktop-app.md`
+
+3. Initialize with a shared template (writes project `instructions.md`):
+
+```bash
+sidecar init --instructions-template web-app
+```
+
+Or load directly from a specific file:
+
+```bash
+sidecar init --instructions-file /absolute/path/to/instructions.md
+```
+
+Notes:
+
+- `--instructions-template <name>` resolves to `~/.sidecar-cli/instructions/<name>.md`.
+- Use either `--instructions-template` or `--instructions-file` (not both).
+- If `instructions.md` already exists, Sidecar will not overwrite it unless `--force` is used.
+
 This creates:
 
 - `.sidecar/sidecar.db`
@@ -100,6 +131,7 @@ This creates:
 - `.sidecar/summary.md`
 - `AGENTS.md` (repo root)
 - `CLAUDE.md` (repo root)
+- `instructions.md` (repo root, only when `--instructions-template` or `--instructions-file` is provided)
 
 Use `--force` to overwrite Sidecar-managed files.
 
@@ -107,7 +139,7 @@ Use `--force` to overwrite Sidecar-managed files.
 
 Global:
 
-- `sidecar init [--force] [--name <project-name>] [--json]`
+- `sidecar init [--force] [--name <project-name>] [--instructions-template <name>] [--instructions-file <path>] [--json]`
 - `sidecar status [--json]`
 - `sidecar preferences show [--json]`
 - `sidecar ui [--no-open] [--port <port>] [--install-only] [--project <path>] [--reinstall]`

package/dist/cli.js

@@ -9,6 +9,7 @@ import { initializeSchema } from './db/schema.js';
 import { findSidecarRoot, getSidecarPaths } from './lib/paths.js';
 import { nowIso, humanTime, stringifyJson } from './lib/format.js';
 import { SidecarError } from './lib/errors.js';
+import { GLOBAL_INSTRUCTIONS_DIR, resolveInstructionsSource } from './lib/instructions.js';
 import { jsonFailure, jsonSuccess, printJsonEnvelope } from './lib/output.js';
 import { bannerDisabled, renderBanner } from './lib/banner.js';
 import { getUpdateNotice } from './lib/update-check.js';
@@ -72,6 +73,17 @@ function respondSuccess(command, asJson, data, lines = []) {
         console.log(line);
     }
 }
+function renderInitBanner() {
+    return [
+        '  [■]─[▪]',
+        '  ███████╗██╗██████╗ ███████╗ ██████╗ █████╗ ██████╗',
+        '  ██╔════╝██║██╔══██╗██╔════╝██╔════╝██╔══██╗██╔══██╗',
+        '  ███████╗██║██║  ██║█████╗  ██║     ███████║██████╔╝',
+        '  ╚════██║██║██║  ██║██╔══╝  ██║     ██╔══██║██╔══██╗',
+        '  ███████║██║██████╔╝███████╗╚██████╗██║  ██║██║  ██║',
+        '  ╚══════╝╚═╝╚═════╝ ╚══════╝ ╚═════╝╚═╝  ╚═╝╚═╝  ╚═╝',
+    ].join('\n');
+}
 function summaryWasRefreshedRecently(db, projectId) {
     return Boolean(db
         .prepare(`SELECT id FROM events WHERE project_id = ? AND type = 'summary_generated' AND created_at >= datetime('now', '-3 day') LIMIT 1`)
@@ -279,14 +291,21 @@ program
     .description('Initialize Sidecar in the current directory')
     .option('--force', 'Overwrite Sidecar files if they already exist')
     .option('--name <project-name>', 'Project name (defaults to current directory name)')
+    .option('--instructions-template <name>', `Load instructions template by name from ${GLOBAL_INSTRUCTIONS_DIR} (example: "web-app")`)
+    .option('--instructions-file <path>', 'Load instructions from a specific markdown file path')
     .option('--json', 'Print machine-readable JSON output')
-    .addHelpText('after', '\nExamples:\n  $ sidecar init\n  $ sidecar init --name "My Project"\n  $ sidecar init --force --json')
+    .addHelpText('after', '\nExamples:\n  $ sidecar init\n  $ sidecar init --name "My Project"\n  $ sidecar init --instructions-template web-app\n  $ sidecar init --instructions-file ~/.sidecar-cli/instructions/desktop.md\n  $ sidecar init --force --json')
     .action((opts) => {
     const command = 'init';
     try {
         const rootPath = process.cwd();
         const sidecar = getSidecarPaths(rootPath);
         const projectName = opts.name?.trim() || path.basename(rootPath);
+        const resolvedInstructions = resolveInstructionsSource({
+            templateName: opts.instructionsTemplate,
+            sourcePath: opts.instructionsFile,
+            cwd: rootPath,
+        });
         if (fs.existsSync(sidecar.sidecarPath)) {
             const stat = fs.lstatSync(sidecar.sidecarPath);
             if (stat.isSymbolicLink()) {
@@ -315,6 +334,13 @@ program
             files.push(sidecar.rootAgentsPath);
         if (shouldWriteRootClaude)
             files.push(sidecar.rootClaudePath);
+        if (resolvedInstructions) {
+            const canWriteInstructions = Boolean(opts.force) || !fs.existsSync(sidecar.rootInstructionsPath);
+            if (!canWriteInstructions) {
+                fail(`Refusing to overwrite ${sidecar.rootInstructionsPath}. Re-run with --force or choose another destination.`);
+            }
+            files.push(sidecar.rootInstructionsPath);
+        }
         fs.mkdirSync(sidecar.sidecarPath, { recursive: true });
         if (opts.force) {
             for (const file of [
@@ -365,6 +391,9 @@ program
         if (shouldWriteRootClaude) {
             fs.writeFileSync(sidecar.rootClaudePath, renderClaudeMarkdown(projectName));
         }
+        if (resolvedInstructions) {
+            fs.writeFileSync(sidecar.rootInstructionsPath, resolvedInstructions.content);
+        }
         const db2 = new DatabaseSync(sidecar.dbPath);
         const refreshed = refreshSummaryFile(db2, rootPath, 1, 10);
         db2.close();
@@ -374,21 +403,18 @@ program
             projectName,
             filesCreated: files,
             summaryGeneratedAt: refreshed.generatedAt,
+            instructionsSource: resolvedInstructions?.sourceLabel ?? null,
             timestamp: nowIso(),
         };
         const shouldShowBanner = !opts.json && !bannerDisabled();
         if (shouldShowBanner) {
-            console.log(renderBanner());
+            console.log(renderInitBanner());
             console.log('');
         }
         respondSuccess(command, Boolean(opts.json), data, [
             `Initialized Sidecar for project: ${projectName}`,
-            'Sidecar provides local project memory for decisions, work logs, tasks, and summaries.',
-            'Created:',
-            ...data.filesCreated.map((f) => `- ${f}`),
-            '',
-            'Next step:',
-            'sidecar context',
+            'Documentation: https://usesidecar.dev/',
+            ...(resolvedInstructions ? ['', `Loaded instructions.md from ${resolvedInstructions.sourceLabel}`] : []),
         ]);
     }
     catch (err) {

package/dist/lib/instructions.js

@@ -0,0 +1,40 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { SidecarError } from './errors.js';
+export const GLOBAL_INSTRUCTIONS_DIR = path.join(os.homedir(), '.sidecar-cli', 'instructions');
+function readInstructionsFile(sourcePath, sourceLabel) {
+    if (!fs.existsSync(sourcePath)) {
+        throw new SidecarError(`Instructions source not found: ${sourcePath}`);
+    }
+    const stat = fs.statSync(sourcePath);
+    if (!stat.isFile()) {
+        throw new SidecarError(`Instructions source is not a file: ${sourcePath}`);
+    }
+    return {
+        sourcePath,
+        sourceLabel,
+        content: fs.readFileSync(sourcePath, 'utf8'),
+    };
+}
+export function resolveInstructionsSource(opts) {
+    const templateName = opts.templateName?.trim();
+    const sourcePath = opts.sourcePath?.trim();
+    if (!templateName && !sourcePath)
+        return null;
+    if (templateName && sourcePath) {
+        throw new SidecarError('Use only one option: --instructions-template or --instructions-file.');
+    }
+    if (sourcePath) {
+        const resolvedPath = path.resolve(opts.cwd, sourcePath);
+        return readInstructionsFile(resolvedPath, `file:${resolvedPath}`);
+    }
+    const fileName = templateName?.endsWith('.md') ? templateName : `${templateName}.md`;
+    if (!fileName)
+        return null;
+    const globalPath = path.join(GLOBAL_INSTRUCTIONS_DIR, fileName);
+    if (!fs.existsSync(globalPath)) {
+        throw new SidecarError(`Instructions template "${templateName}" not found at ${globalPath}. Create it under ${GLOBAL_INSTRUCTIONS_DIR}.`);
+    }
+    return readInstructionsFile(globalPath, `template:${templateName}`);
+}

package/dist/lib/paths.js

@@ -11,6 +11,7 @@ export function getSidecarPaths(rootPath) {
         promptsPath: path.join(sidecarPath, 'prompts'),
         rootAgentsPath: path.join(rootPath, 'AGENTS.md'),
         rootClaudePath: path.join(rootPath, 'CLAUDE.md'),
+        rootInstructionsPath: path.join(rootPath, 'instructions.md'),
         dbPath: path.join(sidecarPath, 'sidecar.db'),
         configPath: path.join(sidecarPath, 'config.json'),
         preferencesPath: path.join(sidecarPath, 'preferences.json'),

package/dist/services/capabilities-service.js

@@ -22,7 +22,7 @@ export function getCapabilitiesManifest(version) {
                 description: 'Initialize Sidecar in the current directory',
                 json_output: true,
                 arguments: [],
-                options: ['--force', '--name <project-name>', '--json'],
+                options: ['--force', '--name <project-name>', '--instructions-template <name>', '--instructions-file <path>', '--json'],
             },
             {
                 name: 'status',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sidecar-cli",
-  "version": "0.1.3",
+  "version": "0.1.4-beta.2",
   "description": "Local-first project memory and recording tool",
   "scripts": {
     "build": "npm run clean && tsc -p tsconfig.json",