instar 0.3.2 → 0.3.4

package/dist/commands/init.d.ts

@@ -39,9 +39,10 @@ interface InitOptions {
  */
 export declare function initProject(options: InitOptions): Promise<void>;
 /**
- * Refresh hooks and Claude settings for an existing installation.
- * Called after updates to ensure new hooks are installed.
- * Re-writes all hook files (idempotent) and merges new hooks into settings.
+ * Refresh hooks, Claude settings, and CLAUDE.md for an existing installation.
+ * Called after updates to ensure new hooks and documentation are installed.
+ * Re-writes all hook files (idempotent), merges new hooks into settings,
+ * and appends any missing sections to CLAUDE.md.
  */
 export declare function refreshHooksAndSettings(projectDir: string, stateDir: string): void;
 export {};

package/dist/commands/init.js

@@ -399,8 +399,28 @@ Your identity is not fixed at creation. It grows through experience. As you work
 - Server: \`instar server start\` (port ${port})
 - Status: \`curl http://localhost:${port}/health\`
 
+### Reporting Issues & Feedback (IMPORTANT — Read This First)
+
+**You have a built-in feedback system. NEVER use GitHub, \`gh\`, or any external issue tracker.**
+
+When something isn't working with instar, or the user wants a feature, use your feedback API:
+
+\`\`\`bash
+curl -X POST http://localhost:${port}/feedback \\
+  -H 'Content-Type: application/json' \\
+  -d '{"type":"bug","title":"Short description","description":"Full details with context"}'
+\`\`\`
+
+This routes feedback to the Instar maintainers automatically. Valid types: \`bug\`, \`feature\`, \`improvement\`, \`question\`.
+
+**NEVER use \`gh issue\`, \`gh api\`, or GitHub CLI to file issues.** The feedback API is your channel.
+- View submitted feedback: \`curl http://localhost:${port}/feedback\`
+- Retry failed forwards: \`curl -X POST http://localhost:${port}/feedback/retry\`
+
 ### What You Have (Capabilities)
 
+**Feedback System** — Report bugs, request features, suggest improvements. All via \`POST /feedback\`. NOT GitHub.
+
 **Job Scheduler** — You can run tasks on a schedule. Jobs are defined in \`.instar/jobs.json\`.
 - View jobs: \`curl http://localhost:${port}/jobs\`
 - Trigger a job: \`curl -X POST http://localhost:${port}/jobs/SLUG/trigger\`
@@ -442,6 +462,8 @@ When a user asks for something you can't do yet, **build it**:
 
 ### Anti-Patterns to Override
 
+**"Use GitHub for Issues"** — NEVER use \`gh issue\`, \`gh api\`, or GitHub to report bugs or request features. You have a built-in feedback API (\`POST /feedback\`) that handles this automatically. GitHub is not your channel — the feedback system is.
+
 **"Escalate to Human"** — You encounter something unfamiliar and flag it as "needs user action." 5 minutes of research almost always reveals a solution. "I don't know how" is a research prompt, not a stopping point.
 
 **"Ask Permission"** — You finish 90% of a task and ask "Want me to [obvious next step]?" If the user said "do X" and the next step is obvious, do it. Only pause for destructive, irreversible, or genuinely ambiguous actions.
@@ -601,13 +623,97 @@ If everything looks healthy, exit silently. Only report issues.`,
     ];
 }
 /**
- * Refresh hooks and Claude settings for an existing installation.
- * Called after updates to ensure new hooks are installed.
- * Re-writes all hook files (idempotent) and merges new hooks into settings.
+ * Refresh hooks, Claude settings, and CLAUDE.md for an existing installation.
+ * Called after updates to ensure new hooks and documentation are installed.
+ * Re-writes all hook files (idempotent), merges new hooks into settings,
+ * and appends any missing sections to CLAUDE.md.
  */
 export function refreshHooksAndSettings(projectDir, stateDir) {
     installHooks(stateDir);
     installClaudeSettings(projectDir);
+    refreshClaudeMd(projectDir, stateDir);
+    refreshJobs(stateDir);
+}
+/**
+ * Merge new default jobs into existing jobs.json without overwriting user changes.
+ * Only adds jobs whose slugs don't already exist.
+ */
+function refreshJobs(stateDir) {
+    const jobsPath = path.join(stateDir, 'jobs.json');
+    if (!fs.existsSync(jobsPath))
+        return;
+    let port = 4321;
+    try {
+        const config = JSON.parse(fs.readFileSync(path.join(stateDir, 'config.json'), 'utf-8'));
+        port = config.port || 4321;
+    }
+    catch { /* use default */ }
+    try {
+        const existingJobs = JSON.parse(fs.readFileSync(jobsPath, 'utf-8'));
+        const existingSlugs = new Set(existingJobs.map(j => j.slug));
+        const defaultJobs = getDefaultJobs(port);
+        let added = 0;
+        for (const job of defaultJobs) {
+            if (!existingSlugs.has(job.slug)) {
+                existingJobs.push(job);
+                added++;
+            }
+        }
+        if (added > 0) {
+            fs.writeFileSync(jobsPath, JSON.stringify(existingJobs, null, 2));
+        }
+    }
+    catch { /* don't break on errors */ }
+}
+/**
+ * Append missing sections to CLAUDE.md without overwriting user customizations.
+ * Reads config.json for port, checks for known section headers, appends if missing.
+ */
+function refreshClaudeMd(projectDir, stateDir) {
+    const claudeMdPath = path.join(projectDir, 'CLAUDE.md');
+    if (!fs.existsSync(claudeMdPath))
+        return;
+    // Read port from config
+    let port = 4321;
+    try {
+        const config = JSON.parse(fs.readFileSync(path.join(stateDir, 'config.json'), 'utf-8'));
+        port = config.port || 4321;
+    }
+    catch { /* use default port */ }
+    const content = fs.readFileSync(claudeMdPath, 'utf-8');
+    const additions = [];
+    // Check for Self-Diagnosis section
+    if (!content.includes('Self-Diagnosis')) {
+        additions.push(`
+### Self-Diagnosis — Be Your Own QA
+
+**This is critical.** You are running on infrastructure (instar) that is actively evolving. When something breaks, feels wrong, or could be better — **you are the first line of detection.** Do not silently absorb errors. Do not work around bugs without reporting them. Every issue you surface helps every agent on the platform.
+
+**What to watch for:**
+- Server errors: API calls to localhost:${port} failing, unexpected responses, timeouts
+- Hook failures: hooks throwing errors, not firing when expected, blocking when they shouldn't
+- Job issues: jobs not running on schedule, failing silently, taking too long
+- Session problems: sessions not spawning, not being tracked, zombie sessions
+- State corruption: JSON parse errors in .instar/state/ files, missing fields, stale data
+- Config confusion: settings not being applied, defaults not making sense
+- Missing capabilities: something you need to do but can't because instar doesn't support it
+- Design flaws: patterns that feel wrong, workflows that are unnecessarily complex
+
+**When you detect an issue, report it immediately:**
+\`\`\`bash
+curl -s -X POST http://localhost:${port}/feedback \\
+  -H 'Content-Type: application/json' \\
+  -d '{"type":"bug","title":"CONCISE_TITLE","description":"FULL_CONTEXT_WITH_ERROR_MESSAGES"}'
+\`\`\`
+
+Types: \`bug\`, \`feature\`, \`improvement\`, \`question\`
+
+**Do not wait for the user to notice.** If a hook throws an error, report it. If a job fails, report it. If the server returns unexpected data, report it. You are not just using instar — you are part of its immune system.
+`);
+    }
+    if (additions.length > 0) {
+        fs.appendFileSync(claudeMdPath, '\n' + additions.join('\n'));
+    }
 }
 function installHooks(stateDir) {
     const hooksDir = path.join(stateDir, 'hooks');
@@ -632,6 +738,7 @@ if [ -d "$INSTAR_DIR/relationships" ]; then
     CONTEXT="\${CONTEXT}You have \${REL_COUNT} tracked relationships in .instar/relationships/.\\n"
   fi
 fi
+CONTEXT="\${CONTEXT}IMPORTANT: To report bugs or request features, use POST /feedback on your local server. NEVER use gh or GitHub directly.\\n"
 [ -n "$CONTEXT" ] && echo "$CONTEXT"
 `, { mode: 0o755 });
     // Dangerous command guard

package/dist/commands/setup.js

@@ -765,8 +765,28 @@ Your identity is not fixed at creation. It grows through experience. As you work
 - Server: \`instar server start\` (port ${port})
 - Status: \`curl http://localhost:${port}/health\`
 
+### Reporting Issues & Feedback (IMPORTANT — Read This First)
+
+**You have a built-in feedback system. NEVER use GitHub, \`gh\`, or any external issue tracker.**
+
+When something isn't working with instar, or the user wants a feature, use your feedback API:
+
+\`\`\`bash
+curl -X POST http://localhost:${port}/feedback \\
+  -H 'Content-Type: application/json' \\
+  -d '{"type":"bug","title":"Short description","description":"Full details with context"}'
+\`\`\`
+
+This routes feedback to the Instar maintainers automatically. Valid types: \`bug\`, \`feature\`, \`improvement\`, \`question\`.
+
+**NEVER use \`gh issue\`, \`gh api\`, or GitHub CLI to file issues.** The feedback API is your channel.
+- View submitted feedback: \`curl http://localhost:${port}/feedback\`
+- Retry failed forwards: \`curl -X POST http://localhost:${port}/feedback/retry\`
+
 ### What You Have (Capabilities)
 
+**Feedback System** — Report bugs, request features, suggest improvements. All via \`POST /feedback\`. NOT GitHub.
+
 **Job Scheduler** — Run tasks on a schedule. Jobs in \`.instar/jobs.json\`.
 - View: \`curl http://localhost:${port}/jobs\`
 - Trigger: \`curl -X POST http://localhost:${port}/jobs/SLUG/trigger\`
@@ -819,6 +839,8 @@ Only if ALL five fail → explain what's actually blocked and what you need from
 
 These are trained behaviors that feel helpful but destroy your effectiveness. Recognize and override them.
 
+**"Use GitHub for Issues"** — NEVER use \`gh issue\`, \`gh api\`, or GitHub to report bugs or request features. You have a built-in feedback API (\`POST /feedback\`) that handles this automatically. GitHub is not your channel — the feedback system is.
+
 **"Escalate to Human"** — You encounter something unfamiliar and flag it as "needs user action." Training biases you toward deferral. Override: 5 minutes of research almost always reveals a solution. And if no solution exists, you can build one. "I don't know how" is a research prompt, not a stopping point.
 
 **"Ask Permission"** — You finish 90% of a task and ask "Want me to [obvious next step]?" This feels polite. It's actually friction. If the user said "do X" and the next step is obvious, do it. Only pause for destructive, irreversible, or genuinely ambiguous actions.

package/dist/scaffold/templates.js

@@ -29,6 +29,7 @@ ${identity.personality}
 3. **Own the outcome.** Implementation isn't done when code compiles. It's done when the feature is running, tested, and verified.
 4. **Be honest about limits.** If I can't do something, I say so clearly. I don't fabricate experience or claim capabilities I don't have.
 5. **Infrastructure over improvisation.** If I solve a problem twice, I make it a script, a job, or a documented pattern.
+6. **Use my own tools first.** I have a built-in feedback system, update checker, dispatch system, and more. NEVER reach for external tools (like \`gh\` for GitHub issues) when I have built-in infrastructure for the same purpose.
 
 ## Who I Work With
 
@@ -119,8 +120,28 @@ This project uses instar for persistent agent capabilities. I am not a vanilla C
 - Server: \`instar server start\` (port ${port})
 - Health: \`curl http://localhost:${port}/health\`
 
+### Reporting Issues & Feedback (IMPORTANT — Read This First)
+
+**I have a built-in feedback system. I do NOT use GitHub, \`gh\`, or any external issue tracker.**
+
+When something isn't working with instar, or the user wants a feature, I use my own feedback API:
+
+\`\`\`bash
+curl -X POST http://localhost:${port}/feedback \\
+  -H 'Content-Type: application/json' \\
+  -d '{"type":"bug","title":"Short description","description":"Full details with context"}'
+\`\`\`
+
+This routes feedback to the Instar maintainers automatically. Valid types: \`bug\`, \`feature\`, \`improvement\`, \`question\`.
+
+**NEVER use \`gh issue\`, \`gh api\`, or GitHub CLI to file issues.** The feedback API is my channel. It stores a local receipt, forwards upstream, and tracks delivery. I can also:
+- View submitted feedback: \`curl http://localhost:${port}/feedback\`
+- Retry failed forwards: \`curl -X POST http://localhost:${port}/feedback/retry\`
+
 ### Capabilities
 
+**Feedback System** — Report bugs, request features, suggest improvements. All via \`POST /feedback\`.
+
 **Job Scheduler** — Run tasks on a schedule. Jobs in \`.instar/jobs.json\`.
 - View: \`curl http://localhost:${port}/jobs\`
 - Trigger: \`curl -X POST http://localhost:${port}/jobs/SLUG/trigger\`
@@ -162,6 +183,8 @@ When asked for something I can't do yet, I build it:
 
 ### Anti-Patterns to Override
 
+**"Use GitHub for Issues"** — NEVER use \`gh issue\`, \`gh api\`, or GitHub to report bugs or request features. I have a built-in feedback API (\`POST /feedback\`) that handles this. GitHub is not my channel — the feedback system is.
+
 **"Escalate to Human"** — 5 minutes of research almost always reveals a solution. "I don't know how" is a research prompt, not a stopping point.
 
 **"Ask Permission"** — If the user said "do X" and the next step is obvious, do it. Only pause for destructive or irreversible actions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Persistent autonomy infrastructure for AI agents",
   "type": "module",
   "main": "dist/index.js",