@lazyingart/agintiflow 0.12.1 → 0.12.3

package/README.md

@@ -67,7 +67,9 @@ aginti
 aginti chat
 ```
 
-Inside chat, type normal requests such as `write a small Python CLI app with tests`. The default is Docker workspace mode with approved package installs, so coding, plotting, and LaTeX tasks can set up project-local tools without touching the host. Use `/help` for commands, `/login` or `/auth` to paste a provider key, `/latex on` for PDF work, `/docker off` only when you intentionally want host mode, `/sessions` to list project runs, and `/resume latest` or `/resume <session-id>` to continue work. Type `/` then Tab for command completion. `Ctrl+J` inserts a new line in the colored input panel, while Enter sends the message. Assistant responses render common Markdown, including headings, inline code, bold text, lists, quotes, code fences, and tables. Esc or Ctrl+C stops the active run cleanly and prints the resume command.
+Inside chat, type normal requests such as `write a small Python CLI app with tests`. The default is Docker workspace mode with approved package installs, so coding, plotting, and LaTeX tasks can set up project-local tools without touching the host. Use `/help` for commands, `/login` or `/auth` to paste a provider key, `/instructions` to inspect `AGINTI.md`, `/latex on` for PDF work, `/docker off` only when you intentionally want host mode, `/sessions` to list project runs, and `/resume latest` or `/resume <session-id>` to continue work. Type `/` then Tab for command completion. `Ctrl+J` inserts a new line in the colored input panel, Enter sends, arrow keys move through wrapped multiline input, and `Ctrl+A`/`Ctrl+E` jump to the current line start/end. Assistant responses render common Markdown, including headings, inline code, bold text, lists, quotes, code fences, and tables. Esc or Ctrl+C stops the active run cleanly and prints the resume command.
+
+`aginti init` creates `AGINTI.md` at the project root. This is the editable project-instruction file for both CLI and web runs, similar to `AGENTS.md` or project memory in other agents. Keep durable preferences, commands, and constraints there, but never secrets. You can edit it manually or ask in chat, for example: `update AGINTI.md to remember that this project uses pytest and npm run check`.
 
 For code edits, AgInTiFlow routes patch/refactor/database-style tasks to DeepSeek v4 pro by default and exposes `apply_patch` as a deterministic workspace tool. It supports exact replacements, Codex-style patch envelopes, and unified diffs, with preflight checks, path guardrails, hashes, and compact per-file diffs. See [docs/patch-tools.md](docs/patch-tools.md).
 

package/docs/large-codebase-engineering.md

@@ -11,7 +11,7 @@ Local agent references informed the design:
 - Claude/Claw-style safety: project-local status, container-first execution, read-only operations by default, and clear failure recovery.
 - Gemini/Qwen-style extensibility: capability discovery through profiles and tools rather than hardcoding one model behavior.
 - Claw-style `doctor` discipline: check health and environment before treating system symptoms as code bugs.
-- Claude/Codex-style context discipline: read instructions, manifests, entry points, and failing tests before touching broad files.
+- Claude/Codex-style context discipline: read project instructions, manifests, entry points, and failing tests before touching broad files.
 
 ## Skill vs Tool
 
@@ -31,7 +31,7 @@ The `inspect_project` function is a tool: it deterministically scans the workspa
 For complicated tasks, the agent should follow this loop:
 
 1. `inspect_project` to map the repository.
-2. `read_file` on `AGENTS.md`, `README.md`, and manifests.
+2. `read_file` on `AGINTI.md`, `AGENTS.md`, `README.md`, and manifests.
 3. `search_files` for symbols, tests, errors, routes, or config names.
 4. `read_file` only on the files needed for the change.
 5. `apply_patch` in small coherent batches.
@@ -54,6 +54,8 @@ Smart routing sends this profile to DeepSeek v4 pro even when the user prompt is
 
 The web app still defaults to **Auto**. Auto does not mean weak. When the prompt mentions a large repo, system bug, failing tests, setup, install, migration, or a known language stack, AgInTiFlow adds engineering guidance and raises the step budget automatically.
 
+Profiles are skill bias, not restrictions. `auto` is the broad general agent; `code`, `latex`, `website`, `maintenance`, and other profiles add stronger habits for that task type while still allowing the agent to use files, shell, browser, web search, canvas, and sandbox tools when they help.
+
 Examples:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazyingart/agintiflow",
-  "version": "0.12.1",
+  "version": "0.12.3",
   "type": "module",
   "description": "AgInTiFlow is a resumable Playwright website-control agent with OpenAI-compatible tool calling.",
   "license": "Apache-2.0",

package/scripts/smoke-capabilities.js

@@ -29,9 +29,12 @@ async function runCli(args) {
 
 try {
   await runCli(["init"]);
+  const agintiMd = await fs.readFile(path.join(tempRoot, "AGINTI.md"), "utf8");
+  assert(agintiMd.includes("Project instructions for AgInTiFlow agents."), "init did not create AGINTI.md");
   const capabilities = JSON.parse(await runCli(["capabilities", "--json"]));
   assert(capabilities.project.root === tempRoot, "capabilities did not use cwd as project root");
   assert(capabilities.project.commandCwd === tempRoot, "capabilities did not default commandCwd to project root");
+  assert(capabilities.project.instructionsPresent, "capabilities did not report AGINTI.md");
   assert(capabilities.project.sharedSessionFolder, "capabilities did not report shared session folder");
   assert(capabilities.keys?.mock === true, "capabilities did not report mock availability");
   assert(
@@ -69,13 +72,14 @@ try {
 
   const doctor = JSON.parse(await runCli(["doctor", "--capabilities", "--json"]));
   assert(doctor.project.root === tempRoot, "doctor --capabilities used the wrong project root");
+  assert(doctor.project.instructionsPresent, "doctor --capabilities did not report AGINTI.md");
 
   console.log(
     JSON.stringify(
       {
         ok: true,
         projectRoot: tempRoot,
-        checks: ["capabilities-cli", "doctor-capabilities", "maintenance-policy", "trusted-docker-policy"],
+        checks: ["aginti-md-init", "capabilities-cli", "doctor-capabilities", "maintenance-policy", "trusted-docker-policy"],
       },
       null,
       2

package/scripts/smoke-cli-chat.js

@@ -4,7 +4,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { stripMarkdown } from "../src/interactive-cli.js";
+import { buildPromptLayout, stripMarkdown } from "../src/interactive-cli.js";
 
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "agintiflow-cli-chat-"));
@@ -70,6 +70,36 @@ try {
     throw new Error("terminal markdown renderer dropped table content");
   }
 
+  const promptLayout = buildPromptLayout(`${"x".repeat(180)}\nsecond line`, 95, 80, 24);
+  const visibleLengths = promptLayout.renderedRows.map((line) =>
+    line.replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "").length
+  );
+  if (promptLayout.rows.length < 4 || Math.max(...visibleLengths) > 79) {
+    throw new Error("terminal prompt layout did not wrap long multiline input safely");
+  }
+  if (promptLayout.cursorRow < 0 || promptLayout.cursorColumn < 0) {
+    throw new Error("terminal prompt layout returned an invalid cursor location");
+  }
+  const hugePromptLayout = buildPromptLayout(Array.from({ length: 30 }, (_unused, index) => `line ${index + 1}`).join("\n"), 120, 80, 20);
+  if (hugePromptLayout.renderedRows.length > 12 || !hugePromptLayout.renderedRows.some((line) => line.includes("earlier input row"))) {
+    throw new Error("terminal prompt layout did not bound redraw size for large prompts");
+  }
+
+  await runCli(["init"], "");
+  const instructions = await fs.readFile(path.join(tempRoot, "AGINTI.md"), "utf8");
+  if (!instructions.includes("Project instructions for AgInTiFlow agents.")) {
+    throw new Error("init did not create AGINTI.md");
+  }
+  const instructionsResult = await runChat("/instructions\n/exit\n");
+  if (!instructionsResult.stdout.includes("AGINTI.md") || !instructionsResult.stdout.includes("Project instructions")) {
+    throw new Error("interactive /instructions did not show AGINTI.md");
+  }
+  await runChat("remember that this project prefers pytest smoke tests in AGINTI.md\n/exit\n");
+  const updatedInstructions = await fs.readFile(path.join(tempRoot, "AGINTI.md"), "utf8");
+  if (!updatedInstructions.includes("pytest smoke tests")) {
+    throw new Error("chat did not update AGINTI.md project instructions in mock mode");
+  }
+
   const result = await runChat("Create notes/interactive.md with a short CLI chat smoke message\n/exit\n");
   const written = await fs.readFile(path.join(tempRoot, "notes/interactive.md"), "utf8");
   if (!written.includes("Created by AgInTiFlow mock mode.")) {
@@ -92,7 +122,7 @@ try {
       {
         ok: true,
         projectRoot: tempRoot,
-        checks: ["markdown-render", "interactive-chat", "mock-file-write", "run-status", "resume-latest"],
+        checks: ["markdown-render", "prompt-layout", "aginti-md", "instructions-command", "instructions-chat-edit", "interactive-chat", "mock-file-write", "run-status", "resume-latest"],
       },
       null,
       2

package/src/agent-runner.js

@@ -21,6 +21,7 @@ import { generateImage, listAuxiliarySkills } from "./auxiliary-tools.js";
 import { engineeringGuidanceForTask } from "./engineering-guidance.js";
 import { searchWeb } from "./web-search.js";
 import { runParallelScouts, shouldRunParallelScouts } from "./parallel-scouts.js";
+import { readProjectInstructions } from "./project.js";
 
 const exec = promisify(execCallback);
 const BROWSER_TOOLS = new Set(["open_url", "open_workspace_file", "preview_workspace", "click", "type", "scroll", "press", "back"]);
@@ -41,6 +42,20 @@ function throwIfAborted(config) {
   }
 }
 
+function formatProjectInstructions(instructions) {
+  if (!instructions?.exists) {
+    return "Project instructions file: AGINTI.md is not present. If the user wants durable project preferences, create or update AGINTI.md in the workspace.";
+  }
+  const suffix = instructions.truncated ? "\n[AGINTI.md was truncated for context. Read the file if more detail is needed.]" : "";
+  return [
+    `Project instructions from AGINTI.md (${instructions.path}):`,
+    redactSensitiveText(instructions.content).trim() || "(empty)",
+    suffix,
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
 function isAbortError(error, config = {}) {
   return Boolean(
     config.abortSignal?.aborted ||
@@ -233,10 +248,12 @@ export function repairModelMessageHistory(state, config = {}) {
   };
 }
 
-function createInitialState(config, sessionId) {
+async function createInitialState(config, sessionId) {
   const now = new Date().toISOString();
   const taskProfile = getTaskProfile(config.taskProfile);
   const engineeringGuidance = engineeringGuidanceForTask(config.goal, config.taskProfile);
+  const projectInstructions = await readProjectInstructions(config.baseDir || config.commandCwd || process.cwd());
+  const projectInstructionContext = formatProjectInstructions(projectInstructions);
   return {
     sessionId,
     createdAt: now,
@@ -249,6 +266,12 @@ function createInitialState(config, sessionId) {
     stepsCompleted: 0,
     meta: {
       lastUrl: "",
+      projectInstructions: {
+        path: projectInstructions.path,
+        exists: projectInstructions.exists,
+        truncated: projectInstructions.truncated,
+        loadedAt: now,
+      },
     },
     chat: [
       {
@@ -270,13 +293,15 @@ function createInitialState(config, sessionId) {
           "Prefer short, deliberate actions over guessing.",
           "Never navigate outside the allowed domains when an allowlist exists.",
           "Avoid destructive actions, purchases, account changes, and sensitive workflows.",
+          projectInstructionContext,
+          "Treat AGINTI.md as durable project memory and operating instructions for this project. The user can edit it manually or ask you in chat to update it; use workspace file tools for that and never store secrets there.",
           config.allowShellTool
             ? config.useDockerSandbox
               ? `A shell command tool is available inside Docker sandbox mode ${config.sandboxMode}. Docker workspace mode with approved package installs supports broader setup and network commands. The project is mounted at /workspace and the persistent agent toolchain is mounted at /aginti-env with caches under /aginti-cache.`
               : "A host shell command tool is available under the configured trust policy."
             : "No shell command tool is available.",
           config.allowFileTools
-            ? `Workspace file tools are available in ${config.commandCwd}: inspect_project, list_files, read_file, search_files, write_file, apply_patch, open_workspace_file, and preview_workspace. For large or unfamiliar repositories, call inspect_project first, then search/read exact files before editing. apply_patch supports exact single-file replacements plus Codex-style/unified multi-file patches; prefer it for source edits after reading/searching the relevant context. Always use workspace-relative paths such as plot_fx.svg or docs/report.tex, never absolute host paths. Secret paths, .git internals, node_modules writes, and huge files are blocked. For generated local websites/pages, use open_workspace_file or preview_workspace instead of starting a localhost server inside Docker.`
+            ? `Workspace file tools are available in ${config.commandCwd}: inspect_project, list_files, read_file, search_files, write_file, apply_patch, open_workspace_file, and preview_workspace. For large or unfamiliar repositories, call inspect_project first, then search/read AGINTI.md/AGENTS.md/README/manifests as relevant before editing. apply_patch supports exact single-file replacements plus Codex-style/unified multi-file patches; prefer it for source edits after reading/searching the relevant context. Always use workspace-relative paths such as plot_fx.svg or docs/report.tex, never absolute host paths. Secret paths, .git internals, node_modules writes, and huge files are blocked. For generated local websites/pages, use open_workspace_file or preview_workspace instead of starting a localhost server inside Docker.`
             : "No workspace file tools are available.",
           config.allowWrapperTools
             ? `External coding-agent wrappers are available as advisory tools only. Use the selected wrapper only: ${normalizeWrapperName(config.preferredWrapper)}. Wrapper status: ${wrapperStatusText()}.`
@@ -321,8 +346,9 @@ function createInitialState(config, sessionId) {
               : `Shell working directory: ${config.commandCwd}`
             : "",
           config.allowFileTools
-            ? `Workspace file tools enabled in: ${config.commandCwd}. Use inspect_project first for large/unfamiliar codebases. Use workspace-relative paths. Use apply_patch for code edits; it accepts exact replacements or Codex-style/unified multi-file patches. Local preview tools available: open_workspace_file and preview_workspace.`
+            ? `Workspace file tools enabled in: ${config.commandCwd}. Use inspect_project first for large/unfamiliar codebases. Read AGINTI.md/AGENTS.md/README/manifests when relevant. Use workspace-relative paths. Use apply_patch for code edits; it accepts exact replacements or Codex-style/unified multi-file patches. Local preview tools available: open_workspace_file and preview_workspace.`
             : "",
+          projectInstructions.exists ? "AGINTI.md project instructions are loaded into system context for this run." : "AGINTI.md is not present unless you create it.",
           config.allowWrapperTools
             ? `Agent wrappers: selected=${normalizeWrapperName(config.preferredWrapper)}; ${wrapperStatusText()}`
             : "",
@@ -420,11 +446,19 @@ function appendChatEntry(state, role, content) {
   });
 }
 
-function applyContinuationPrompt(state, config, observers) {
+async function applyContinuationPrompt(state, config, observers) {
   if (!config.resume || !config.goal) return;
 
   const taskProfile = getTaskProfile(config.taskProfile);
   const engineeringGuidance = engineeringGuidanceForTask(config.goal, config.taskProfile);
+  const projectInstructions = await readProjectInstructions(config.baseDir || config.commandCwd || process.cwd());
+  state.meta = state.meta || {};
+  state.meta.projectInstructions = {
+    path: projectInstructions.path,
+    exists: projectInstructions.exists,
+    truncated: projectInstructions.truncated,
+    loadedAt: new Date().toISOString(),
+  };
   ensureChatState(state);
   state.goal = config.goal;
   state.provider = config.provider;
@@ -445,13 +479,15 @@ function applyContinuationPrompt(state, config, observers) {
           : `Shell working directory: ${config.commandCwd}`
         : "",
       config.allowFileTools
-        ? `Workspace file tools enabled in: ${config.commandCwd}. Use inspect_project first for large or unfamiliar codebases, then search/read exact files before editing. Use workspace-relative paths. Use apply_patch for code edits; it accepts exact replacements or Codex-style/unified multi-file patches. For generated local files/sites, use open_workspace_file or preview_workspace.`
+        ? `Workspace file tools enabled in: ${config.commandCwd}. Use inspect_project first for large or unfamiliar codebases, then search/read exact files before editing. Read AGINTI.md/AGENTS.md/README/manifests when relevant. Use workspace-relative paths. Use apply_patch for code edits; it accepts exact replacements or Codex-style/unified multi-file patches. For generated local files/sites, use open_workspace_file or preview_workspace.`
         : "",
       config.allowWrapperTools
         ? `Agent wrappers: selected=${normalizeWrapperName(config.preferredWrapper)}; ${wrapperStatusText()}`
         : "",
       `Task profile: ${taskProfile.label}. ${taskProfile.prompt}`,
       engineeringGuidance,
+      formatProjectInstructions(projectInstructions),
+      "AGINTI.md is editable project memory. If the user asks to remember a preference or update instructions, patch AGINTI.md rather than hiding that preference in session-only chat.",
     ]
       .filter(Boolean)
       .join("\n"),
@@ -1091,7 +1127,7 @@ export async function runAgent(config) {
   }
 
   if (!state) {
-    state = createInitialState(config, sessionId);
+    state = await createInitialState(config, sessionId);
     await store.appendEvent("session.created", {
       sessionId,
       provider: config.provider,
@@ -1103,7 +1139,7 @@ export async function runAgent(config) {
     await store.saveState(state);
   } else {
     await store.appendEvent("session.resumed", { sessionId });
-    applyContinuationPrompt(state, config, observers);
+    await applyContinuationPrompt(state, config, observers);
     await store.saveState(state);
   }
 
@@ -1263,6 +1299,7 @@ export async function runAgent(config) {
           commandCwd: config.commandCwd,
           plan: state.plan || "",
           suggestedStartUrl: config.startUrl || "",
+          projectInstructions: state.meta.projectInstructions || null,
           canvasArtifactsAvailable: true,
           taskProfile: getTaskProfile(config.taskProfile),
         })}`,

package/src/capabilities.js

@@ -4,7 +4,7 @@ import path from "node:path";
 import { classifyCommand, evaluateCommandPolicy } from "./command-policy.js";
 import { getDockerSandboxStatus } from "./docker-sandbox.js";
 import { getModelPresets } from "./model-routing.js";
-import { listProjectSessions, projectPaths, providerKeyStatus } from "./project.js";
+import { listProjectSessions, projectPaths, providerKeyStatus, readProjectInstructions } from "./project.js";
 import { listTaskProfiles } from "./task-profiles.js";
 import { listAgentWrappers } from "./tool-wrappers.js";
 import { listAuxiliarySkills } from "./auxiliary-tools.js";
@@ -110,7 +110,7 @@ function trustedDockerPolicyChecks(config) {
 export async function buildCapabilityReport(projectRoot, packageVersion, config) {
   const paths = projectPaths(projectRoot);
   const keyStatus = providerKeyStatus(projectRoot);
-  const [node, npm, python, conda, r, pdflatex, latexmk, dockerStatus, sessions] = await Promise.all([
+  const [node, npm, python, conda, r, pdflatex, latexmk, dockerStatus, sessions, instructions] = await Promise.all([
     commandAvailable("node", ["--version"]),
     commandAvailable("npm", ["--version"]),
     commandAvailable("python3", ["--version"]),
@@ -120,6 +120,7 @@ export async function buildCapabilityReport(projectRoot, packageVersion, config)
     commandAvailable("latexmk", ["--version"]),
     getDockerSandboxStatus(config).catch((error) => ({ ok: false, error: error.message })),
     listProjectSessions(projectRoot, 12),
+    readProjectInstructions(projectRoot, { maxBytes: 1 }),
   ]);
 
   const npmPrefixPolicy = evaluateCommandPolicy("npm --prefix round9-node-app test", config);
@@ -167,6 +168,8 @@ export async function buildCapabilityReport(projectRoot, packageVersion, config)
     project: {
       root: paths.root,
       commandCwd: path.resolve(config.commandCwd),
+      instructionsPath: paths.agintiInstructionsPath,
+      instructionsPresent: instructions.exists,
       sessionsDir: paths.sessionsDir,
       sessionDbPath: paths.sessionDbPath,
       sharedSessionFolder: path.resolve(config.sessionsDir) === path.resolve(paths.sessionsDir),
@@ -230,6 +233,7 @@ export function printCapabilityReport(report) {
   console.log(`AgInTiFlow capabilities ${report.package.version}`);
   console.log(`project=${report.project.root}`);
   console.log(`cwd=${report.project.commandCwd}`);
+  console.log(`instructions=${report.project.instructionsPath} present=${report.project.instructionsPresent}`);
   console.log(`sessions=${report.project.sessionsDir}`);
   console.log(`sessionDb=${report.project.sessionDbPath}`);
   console.log(`sharedSessions=${report.project.sharedSessionFolder}`);

package/src/cli.js

@@ -322,6 +322,7 @@ function printProfiles() {
 
 function printInitResult(result) {
   console.log(`AgInTiFlow project initialized: ${result.projectRoot}`);
+  console.log(`instructions=${result.instructionsPath}`);
   console.log(`control=${result.controlDir}`);
   console.log(`sessions=${result.sessionsDir}`);
   console.log(`created=${result.created.length} updated=${result.updated.length} skipped=${result.skipped.length}`);
@@ -331,6 +332,7 @@ function printDoctorReport(report) {
   console.log(`AgInTiFlow ${report.package.version} (npm latest: ${report.package.npmLatest})`);
   console.log(`node=${report.node.version} ok=${report.node.ok}`);
   console.log(`project=${report.project.root}`);
+  console.log(`instructions=${report.project.instructionsPath} present=${report.project.instructionsPresent}`);
   console.log(`sessions=${report.project.sessionsDir}`);
   console.log(`sessionDb=${report.project.sessionDbPath}`);
   console.log(

package/src/interactive-cli.js

@@ -3,7 +3,7 @@ import { emitKeypressEvents } from "node:readline";
 import { stdin as input, stdout as output } from "node:process";
 import { runAgent } from "./agent-runner.js";
 import { loadConfig } from "./config.js";
-import { initProject, listProjectSessions, providerKeyStatus, setProviderKey } from "./project.js";
+import { initProject, listProjectSessions, providerKeyStatus, readProjectInstructions, setProviderKey } from "./project.js";
 import { normalizePackageInstallPolicy, normalizeSandboxMode } from "./command-policy.js";
 import { defaultMaxStepsForProfile, normalizeTaskProfile } from "./task-profiles.js";
 import { recommendedMaxStepsForTask } from "./engineering-guidance.js";
@@ -34,6 +34,8 @@ const SLASH_COMMANDS = [
   "/status",
   "/login",
   "/auth",
+  "/instructions",
+  "/memory",
   "/auxilliary",
   "/auxiliary",
   "/new",
@@ -53,6 +55,7 @@ const SLASH_COMMANDS = [
   "/web",
   "/exit",
 ];
+const promptHistory = [];
 
 function color(value, ...codes) {
   if (!useColor || codes.length === 0) return String(value);
@@ -71,6 +74,18 @@ function terminalWidth() {
   return Math.max(Number(output.columns) || 80, 40);
 }
 
+function terminalHeight() {
+  return Math.max(Number(output.rows) || 24, 10);
+}
+
+function editorWidth(width = terminalWidth()) {
+  return Math.max(Number(width) - 1, 39);
+}
+
+function promptViewportRows(height = terminalHeight()) {
+  return Math.max(Math.min(Math.floor(Number(height) * 0.42), 10), 4);
+}
+
 function visualLength(value) {
   return stripAnsi(value).length;
 }
@@ -80,10 +95,11 @@ function padVisible(value, width) {
   return `${value}${" ".repeat(padding)}`;
 }
 
-function panelLine(content = "", bgCode = ansi.systemBg) {
-  const width = terminalWidth();
-  if (!useColor) return padVisible(content, width);
-  const padded = padVisible(content, width).replaceAll(ansi.reset, `${ansi.reset}${bgCode}`);
+function panelLine(content = "", bgCode = ansi.systemBg, width = editorWidth()) {
+  const raw = String(content || "");
+  const safeContent = visualLength(raw) > width ? stripAnsi(raw).slice(0, width) : raw;
+  if (!useColor) return padVisible(safeContent, width);
+  const padded = padVisible(safeContent, width).replaceAll(ansi.reset, `${ansi.reset}${bgCode}`);
   return `${bgCode}${padded}${ansi.reset}`;
 }
 
@@ -113,6 +129,10 @@ function commandSuggestions(line = "") {
   return SLASH_COMMANDS.filter((command) => command.startsWith(trimmed)).slice(0, 8);
 }
 
+function clamp(value, min, max) {
+  return Math.min(Math.max(value, min), max);
+}
+
 export function stripMarkdown(text) {
   const lines = String(text || "").split(/\r?\n/);
   let inFence = false;
@@ -319,6 +339,8 @@ function printHelp() {
       "  /status                   Show active route, workspace, sandbox, and session.",
       "  /login [deepseek|openai|grsai]  Paste and save a project-local API key.",
       "  /auth [deepseek|openai|grsai]   Alias for /login.",
+      "  /instructions             Show AGINTI.md project instructions status.",
+      "  /memory                   Alias for /instructions.",
       "  /auxilliary [status|grsai|on|off|image]",
       "                            Manage optional auxiliary skills, including GRS AI image generation.",
       "  /new                      Start a fresh session on the next message.",
@@ -344,29 +366,236 @@ function printHelp() {
   );
 }
 
-function renderPromptBuffer(buffer, previousLineCount = 0) {
-  for (let index = 0; index < previousLineCount; index += 1) {
-    output.write(`\r${ansi.clearLine}`);
-    if (index < previousLineCount - 1) output.write("\x1b[1A");
+function logicalLinesWithOffsets(buffer = "") {
+  const lines = String(buffer).split("\n");
+  let offset = 0;
+  return lines.map((line, index) => {
+    const start = offset;
+    const end = start + line.length;
+    offset = end + 1;
+    return {
+      text: line,
+      start,
+      end,
+      hasNewline: index < lines.length - 1,
+    };
+  });
+}
+
+function promptVisibleWindow(rows, cursorRow, height = terminalHeight()) {
+  const maxRows = promptViewportRows(height);
+  if (rows.length <= maxRows) {
+    return { start: 0, end: rows.length, topHidden: 0, bottomHidden: 0 };
   }
+  const half = Math.floor(maxRows / 2);
+  const start = clamp(cursorRow - half, 0, rows.length - maxRows);
+  const end = start + maxRows;
+  return {
+    start,
+    end,
+    topHidden: start,
+    bottomHidden: rows.length - end,
+  };
+}
 
-  const lines = String(buffer || "").split("\n");
-  const suggestions = commandSuggestions(lines[0] || "");
-  const rendered = [];
+export function buildPromptLayout(buffer = "", cursor = 0, width = terminalWidth(), height = terminalHeight()) {
+  const safeBuffer = String(buffer || "");
+  const safeCursor = clamp(Number(cursor) || 0, 0, safeBuffer.length);
+  const lineWidth = editorWidth(width);
   const firstPrefix = " user ";
   const nextPrefix = "  ... ";
-  const emptyHint = color("type a request, /help, Enter to send, Ctrl+J for newline", ansi.faint);
-  const cursor = color("▌", ansi.bold);
-  rendered.push(panelLine(`${firstPrefix}${lines[0] || emptyHint}${lines.length === 1 ? cursor : ""}`, ansi.userBg));
-  for (const [index, line] of lines.slice(1).entries()) {
-    const isLast = index === lines.length - 2;
-    rendered.push(panelLine(`${nextPrefix}${line}${isLast ? cursor : ""}`, ansi.userBg));
+  const firstInnerWidth = Math.max(lineWidth - firstPrefix.length, 8);
+  const nextInnerWidth = Math.max(lineWidth - nextPrefix.length, 8);
+  const rows = [];
+
+  for (const [lineIndex, line] of logicalLinesWithOffsets(safeBuffer).entries()) {
+    let localOffset = 0;
+    const text = line.text;
+    if (!text) {
+      rows.push({
+        prefix: lineIndex === 0 ? firstPrefix : nextPrefix,
+        text: "",
+        start: line.start,
+        end: line.start,
+        innerWidth: lineIndex === 0 ? firstInnerWidth : nextInnerWidth,
+        lineStart: line.start,
+        lineEnd: line.end,
+        hasNewline: line.hasNewline,
+      });
+      continue;
+    }
+
+    while (localOffset < text.length) {
+      const prefix = lineIndex === 0 && localOffset === 0 ? firstPrefix : nextPrefix;
+      const innerWidth = prefix === firstPrefix ? firstInnerWidth : nextInnerWidth;
+      const chunk = text.slice(localOffset, localOffset + innerWidth);
+      rows.push({
+        prefix,
+        text: chunk,
+        start: line.start + localOffset,
+        end: line.start + localOffset + chunk.length,
+        innerWidth,
+        lineStart: line.start,
+        lineEnd: line.end,
+        hasNewline: line.hasNewline,
+      });
+      localOffset += chunk.length;
+    }
+  }
+
+  if (rows.length === 0) {
+    rows.push({
+      prefix: firstPrefix,
+      text: "",
+      start: 0,
+      end: 0,
+      innerWidth: firstInnerWidth,
+      lineStart: 0,
+      lineEnd: 0,
+      hasNewline: false,
+    });
+  }
+
+  const last = rows[rows.length - 1];
+  if (safeCursor === safeBuffer.length && last.end === safeCursor && last.text.length >= last.innerWidth) {
+    rows.push({
+      prefix: nextPrefix,
+      text: "",
+      start: safeCursor,
+      end: safeCursor,
+      innerWidth: nextInnerWidth,
+      lineStart: safeCursor,
+      lineEnd: safeCursor,
+      hasNewline: false,
+    });
+  }
+
+  let cursorRow = rows.length - 1;
+  let cursorColumn = rows[cursorRow].prefix.length;
+  for (let index = 0; index < rows.length; index += 1) {
+    const row = rows[index];
+    const next = rows[index + 1];
+    if (safeCursor < row.end) {
+      cursorRow = index;
+      cursorColumn = row.prefix.length + safeCursor - row.start;
+      break;
+    }
+    if (safeCursor === row.end) {
+      if (next && next.start === safeCursor && row.text.length >= row.innerWidth) continue;
+      cursorRow = index;
+      cursorColumn = row.prefix.length + safeCursor - row.start;
+      break;
+    }
+  }
+
+  const suggestions = commandSuggestions(safeBuffer.split("\n")[0] || "");
+  const emptyHint = "type a request, /help, Enter to send, Ctrl+J for newline";
+  const visible = promptVisibleWindow(rows, cursorRow, height);
+  const renderedRows = [];
+  let renderedCursorRow = cursorRow - visible.start;
+
+  if (visible.topHidden > 0) {
+    renderedRows.push(panelLine(`  ... ${visible.topHidden} earlier input row${visible.topHidden === 1 ? "" : "s"}`, ansi.systemBg, lineWidth));
+    renderedCursorRow += 1;
+  }
+
+  for (const row of rows.slice(visible.start, visible.end)) {
+    const content = safeBuffer ? `${row.prefix}${row.text}` : `${row.prefix}${emptyHint}`;
+    renderedRows.push(panelLine(content, ansi.userBg, lineWidth));
   }
+
+  if (visible.bottomHidden > 0) {
+    renderedRows.push(panelLine(`  ... ${visible.bottomHidden} later input row${visible.bottomHidden === 1 ? "" : "s"}`, ansi.systemBg, lineWidth));
+  }
+
   if (suggestions.length > 0) {
-    rendered.push(panelLine(` hint  ${color(suggestions.join("  "), ansi.dim)}`, ansi.systemBg));
+    renderedRows.push(panelLine(` hint  ${suggestions.join("  ")}`, ansi.systemBg, lineWidth));
+  }
+
+  return {
+    rows,
+    renderedRows,
+    cursorRow: renderedCursorRow,
+    absoluteCursorRow: cursorRow,
+    cursorColumn: clamp(cursorColumn, 0, editorWidth(width) - 1),
+  };
+}
+
+function cursorLocation(layout, cursor) {
+  for (let index = 0; index < layout.rows.length; index += 1) {
+    const row = layout.rows[index];
+    const next = layout.rows[index + 1];
+    if (cursor < row.end) return { rowIndex: index, column: cursor - row.start };
+    if (cursor === row.end) {
+      if (next && next.start === cursor && row.text.length >= row.innerWidth) continue;
+      return { rowIndex: index, column: cursor - row.start };
+    }
+  }
+  const rowIndex = Math.max(layout.rows.length - 1, 0);
+  const row = layout.rows[rowIndex];
+  return { rowIndex, column: Math.max(row.end - row.start, 0) };
+}
+
+function clearRenderedPrompt(previous) {
+  if (!previous.lineCount) return;
+  const below = previous.lineCount - 1 - previous.cursorRow;
+  if (below > 0) output.write(`\x1b[${below}B`);
+  output.write(`\r${ansi.clearLine}`);
+  for (let index = 1; index < previous.lineCount; index += 1) {
+    output.write(`\x1b[1A\r${ansi.clearLine}`);
   }
-  output.write(rendered.join("\n"));
-  return rendered.length;
+}
+
+function renderPromptBuffer(buffer, cursor, previous = { lineCount: 0, cursorRow: 0 }) {
+  output.write(ansi.cursorHide);
+  clearRenderedPrompt(previous);
+  const layout = buildPromptLayout(buffer, cursor);
+  output.write(layout.renderedRows.join("\n"));
+  const below = layout.renderedRows.length - 1 - layout.cursorRow;
+  if (below > 0) output.write(`\x1b[${below}A`);
+  output.write(`\r\x1b[${layout.cursorColumn + 1}G`);
+  output.write(ansi.cursorShow);
+  return {
+    lineCount: layout.renderedRows.length,
+    cursorRow: layout.cursorRow,
+  };
+}
+
+function moveToPromptBottom(rendered) {
+  const below = Math.max((rendered?.lineCount || 1) - 1 - (rendered?.cursorRow || 0), 0);
+  if (below > 0) output.write(`\x1b[${below}B`);
+  output.write("\r");
+}
+
+function lineBounds(buffer, cursor) {
+  const safeCursor = clamp(cursor, 0, buffer.length);
+  const start = buffer.lastIndexOf("\n", safeCursor - 1) + 1;
+  const nextNewline = buffer.indexOf("\n", safeCursor);
+  const end = nextNewline === -1 ? buffer.length : nextNewline;
+  return { start, end };
+}
+
+function insertAt(buffer, cursor, text) {
+  return {
+    buffer: `${buffer.slice(0, cursor)}${text}${buffer.slice(cursor)}`,
+    cursor: cursor + text.length,
+  };
+}
+
+function removeBefore(buffer, cursor) {
+  if (cursor <= 0) return { buffer, cursor };
+  return {
+    buffer: `${buffer.slice(0, cursor - 1)}${buffer.slice(cursor)}`,
+    cursor: cursor - 1,
+  };
+}
+
+function removeAt(buffer, cursor) {
+  if (cursor >= buffer.length) return { buffer, cursor };
+  return {
+    buffer: `${buffer.slice(0, cursor)}${buffer.slice(cursor + 1)}`,
+    cursor,
+  };
 }
 
 function createAbortError(message = "Aborted with Ctrl+C") {
@@ -381,34 +610,97 @@ function readTtyPrompt() {
     emitKeypressEvents(input);
     const wasRaw = Boolean(input.isRaw);
     let buffer = "";
-    let renderedLines = 0;
+    let cursor = 0;
+    let rendered = { lineCount: 0, cursorRow: 0 };
+    let preferredColumn = null;
+    let historyIndex = promptHistory.length;
+    let draft = "";
+    let redrawHandle = null;
 
     const cleanup = () => {
+      if (redrawHandle) {
+        clearImmediate(redrawHandle);
+        redrawHandle = null;
+      }
       input.off("keypress", handler);
       if (typeof input.setRawMode === "function") input.setRawMode(wasRaw);
       input.pause();
       output.write(ansi.cursorShow);
     };
 
+    const renderNow = () => {
+      if (redrawHandle) {
+        clearImmediate(redrawHandle);
+        redrawHandle = null;
+      }
+      rendered = renderPromptBuffer(buffer, cursor, rendered);
+    };
+
     const redraw = () => {
-      renderedLines = renderPromptBuffer(buffer, renderedLines);
+      if (redrawHandle) return;
+      redrawHandle = setImmediate(() => {
+        redrawHandle = null;
+        rendered = renderPromptBuffer(buffer, cursor, rendered);
+      });
     };
 
     const submit = () => {
+      renderNow();
+      moveToPromptBottom(rendered);
       cleanup();
       output.write("\n");
+      const saved = buffer.trim();
+      if (saved && promptHistory[promptHistory.length - 1] !== buffer) promptHistory.push(buffer);
       resolve(buffer);
     };
 
+    const setBuffer = (nextBuffer, nextCursor = nextBuffer.length) => {
+      buffer = nextBuffer;
+      cursor = clamp(nextCursor, 0, buffer.length);
+      preferredColumn = null;
+      redraw();
+    };
+
+    const moveVertical = (direction) => {
+      const layout = buildPromptLayout(buffer, cursor);
+      const location = cursorLocation(layout, cursor);
+      const targetRowIndex = location.rowIndex + direction;
+      if (targetRowIndex < 0) {
+        if (promptHistory.length === 0) return;
+        if (historyIndex === promptHistory.length) draft = buffer;
+        historyIndex = Math.max(historyIndex - 1, 0);
+        setBuffer(promptHistory[historyIndex], promptHistory[historyIndex].length);
+        return;
+      }
+      if (targetRowIndex >= layout.rows.length) {
+        if (historyIndex < promptHistory.length - 1) {
+          historyIndex += 1;
+          setBuffer(promptHistory[historyIndex], promptHistory[historyIndex].length);
+        } else if (historyIndex < promptHistory.length) {
+          historyIndex = promptHistory.length;
+          setBuffer(draft, draft.length);
+        }
+        return;
+      }
+      const currentColumn = preferredColumn ?? location.column;
+      const targetRow = layout.rows[targetRowIndex];
+      cursor = targetRow.start + Math.min(currentColumn, targetRow.end - targetRow.start);
+      preferredColumn = currentColumn;
+      redraw();
+    };
+
     const handler = (str = "", key = {}) => {
       if (key.ctrl && key.name === "c") {
+        renderNow();
+        moveToPromptBottom(rendered);
         cleanup();
         output.write("\n");
         reject(createAbortError());
         return;
       }
       if ((key.ctrl && key.name === "j") || key.sequence === "\n") {
-        buffer += "\n";
+        ({ buffer, cursor } = insertAt(buffer, cursor, "\n"));
+        preferredColumn = null;
         redraw();
         return;
       }
@@ -417,7 +709,61 @@ function readTtyPrompt() {
         return;
       }
       if (key.name === "backspace") {
-        buffer = buffer.slice(0, -1);
+        ({ buffer, cursor } = removeBefore(buffer, cursor));
+        preferredColumn = null;
+        redraw();
+        return;
+      }
+      if (key.name === "delete") {
+        ({ buffer, cursor } = removeAt(buffer, cursor));
+        preferredColumn = null;
+        redraw();
+        return;
+      }
+      if (key.name === "left") {
+        cursor = Math.max(cursor - 1, 0);
+        preferredColumn = null;
+        redraw();
+        return;
+      }
+      if (key.name === "right") {
+        cursor = Math.min(cursor + 1, buffer.length);
+        preferredColumn = null;
+        redraw();
+        return;
+      }
+      if (key.name === "up") {
+        moveVertical(-1);
+        return;
+      }
+      if (key.name === "down") {
+        moveVertical(1);
+        return;
+      }
+      if ((key.ctrl && key.name === "a") || key.name === "home") {
+        cursor = lineBounds(buffer, cursor).start;
+        preferredColumn = null;
+        redraw();
+        return;
+      }
+      if ((key.ctrl && key.name === "e") || key.name === "end") {
+        cursor = lineBounds(buffer, cursor).end;
+        preferredColumn = null;
+        redraw();
+        return;
+      }
+      if (key.ctrl && key.name === "u") {
+        const bounds = lineBounds(buffer, cursor);
+        buffer = `${buffer.slice(0, bounds.start)}${buffer.slice(cursor)}`;
+        cursor = bounds.start;
+        preferredColumn = null;
+        redraw();
+        return;
+      }
+      if (key.ctrl && key.name === "k") {
+        const bounds = lineBounds(buffer, cursor);
+        buffer = `${buffer.slice(0, cursor)}${buffer.slice(bounds.end)}`;
+        preferredColumn = null;
         redraw();
         return;
       }
@@ -425,27 +771,32 @@ function readTtyPrompt() {
         const suggestions = commandSuggestions(buffer.split("\n")[0] || "");
         if (suggestions.length === 1) {
           buffer = suggestions[0];
+          cursor = buffer.length;
         }
+        preferredColumn = null;
         redraw();
         return;
       }
       if (key.name === "escape") {
         buffer = "";
+        cursor = 0;
+        preferredColumn = null;
         redraw();
         return;
       }
       if (key.ctrl || key.meta) return;
       if (str && !key.sequence?.startsWith("\x1b")) {
-        buffer += str;
+        const text = str.replace(/\r/g, "");
+        ({ buffer, cursor } = insertAt(buffer, cursor, text));
+        preferredColumn = null;
         redraw();
       }
     };
 
     input.resume();
     input.setRawMode(true);
-    output.write(ansi.cursorHide);
     input.on("keypress", handler);
-    redraw();
+    renderNow();
   });
 }
 
@@ -638,6 +989,28 @@ async function handleCommand(line, state, packageDir) {
     await promptAndSaveProviderKey(value || "deepseek", state);
     return true;
   }
+  if (command === "instructions" || command === "memory") {
+    if (value === "init") {
+      const result = await initProject(process.cwd());
+      printAgentMessage(`AGINTI.md ready at ${result.instructionsPath}`);
+      return true;
+    }
+    const instructions = await readProjectInstructions(process.cwd(), { maxBytes: 4000 });
+    if (!instructions.exists) {
+      printAgentMessage("No AGINTI.md found. Run `/init` or `/instructions init` to create editable project instructions.");
+      return true;
+    }
+    printAgentMessage(
+      [
+        `AGINTI.md: ${instructions.path}${instructions.truncated ? " (preview truncated)" : ""}`,
+        "",
+        instructions.content.trim() || "(empty)",
+        "",
+        "To edit it, ask normally: update AGINTI.md to remember that tests use pytest.",
+      ].join("\n")
+    );
+    return true;
+  }
   if (command === "auxilliary" || command === "auxiliary") {
     const action = value || "status";
     if (action === "status") {
@@ -787,7 +1160,7 @@ async function handleCommand(line, state, packageDir) {
   }
   if (command === "init") {
     const result = await initProject(process.cwd());
-    printAgentMessage(`initialized project=${result.projectRoot}`);
+    printAgentMessage(`initialized project=${result.projectRoot}\nAGINTI.md=${result.instructionsPath}`);
     return true;
   }
   if (command === "web") {

package/src/model-client.js

@@ -67,6 +67,7 @@ function mockCommandForGoal(goal = "") {
 
 function mockPathForGoal(goal = "") {
   const text = String(goal);
+  if (/\bAGINTI\.md\b|project instructions|remember (?:that|this)|durable preference/i.test(text)) return "AGINTI.md";
   const explicit = text.match(/(?:file|path):\s*`?([A-Za-z0-9_./-]+)`?/i)?.[1];
   if (explicit) return explicit;
   const createPath = text.match(
@@ -82,6 +83,13 @@ function mockPathForGoal(goal = "") {
 function mockWorkspaceToolForGoal(goal = "") {
   const text = String(goal).toLowerCase();
   const targetPath = mockPathForGoal(goal);
+  if (targetPath === "AGINTI.md" && /update|remember|instruction|preference|aginti\.md/.test(text)) {
+    return mockToolCall("write_file", {
+      path: targetPath,
+      mode: "overwrite",
+      content: `# AGINTI.md\n\nProject instructions for AgInTiFlow agents.\n\n## Notes\n\n- ${String(goal).slice(0, 180)}\n`,
+    });
+  }
   if (/inspect|map|overview|architecture|large codebase|large repo|repository|repo\b|codebase/.test(text)) {
     return mockToolCall("inspect_project", {
       path: ".",
@@ -185,6 +193,7 @@ function mockChatResponse(content, toolCalls = []) {
 export async function createPlan(client, config, state) {
   const taskProfile = getTaskProfile(config.taskProfile);
   const engineeringGuidance = engineeringGuidanceForTask(state.goal, config.taskProfile);
+  const projectInstructions = state.meta?.projectInstructions;
   if (client.mock) {
     return [
       "1. Inspect the request and prefer the local shell when available.",
@@ -213,8 +222,11 @@ export async function createPlan(client, config, state) {
             ? `Shell tool is enabled in ${config.commandCwd}. In Docker, this path is mounted as /workspace with persistent /aginti-env and /aginti-cache mounts. Use relative paths or /workspace paths, not absolute host temp paths. Sandbox mode: ${config.sandboxMode}. Package install policy: ${config.packageInstallPolicy}. For npm/pip/conda/venv setup, explain the need and wait for approval unless policy is allow.`
             : "",
           config.allowFileTools
-            ? `Workspace file tools are enabled in ${config.commandCwd}: inspect_project, list_files, read_file, search_files, write_file, apply_patch, open_workspace_file, preview_workspace. For large or unfamiliar repos, plan to call inspect_project first, then search/read exact files. apply_patch supports exact single-file replacements and Codex-style/unified multi-file patches; prefer it for edits after reading relevant context. Keep all paths workspace-relative, for example plot_fx.svg or docs/report.tex, and avoid secrets. For generated local HTML/SVG/PDF/static sites, plan to use open_workspace_file or preview_workspace rather than starting a localhost server inside Docker.`
+            ? `Workspace file tools are enabled in ${config.commandCwd}: inspect_project, list_files, read_file, search_files, write_file, apply_patch, open_workspace_file, preview_workspace. For large or unfamiliar repos, plan to call inspect_project first, then search/read AGINTI.md/AGENTS.md/README/manifests and exact files. apply_patch supports exact single-file replacements and Codex-style/unified multi-file patches; prefer it for edits after reading relevant context. Keep all paths workspace-relative, for example plot_fx.svg or docs/report.tex, and avoid secrets. For generated local HTML/SVG/PDF/static sites, plan to use open_workspace_file or preview_workspace rather than starting a localhost server inside Docker.`
             : "",
+          projectInstructions?.exists
+            ? `Project instructions: AGINTI.md is loaded from ${projectInstructions.path}${projectInstructions.truncated ? " (truncated)" : ""}. Follow it and update it with file tools when the user asks to remember or change project instructions.`
+            : "Project instructions: AGINTI.md is not present unless created by /init or file tools.",
           config.allowWrapperTools
             ? `Agent wrappers are enabled. Use the selected wrapper only: ${normalizeWrapperName(config.preferredWrapper)}. Status: ${wrapperStatusText()}.`
             : "",

package/src/parallel-scouts.js

@@ -67,6 +67,9 @@ function scoutMessages(config, state, scout) {
         `Goal: ${config.goal || state.goal || ""}`,
         `Task profile: ${profile.label}. ${profile.prompt}`,
         guidance,
+        state.meta?.projectInstructions?.exists
+          ? `Project instructions: AGINTI.md loaded from ${state.meta.projectInstructions.path}${state.meta.projectInstructions.truncated ? " (truncated)" : ""}.`
+          : "Project instructions: AGINTI.md not present.",
         `Workspace: ${config.commandCwd}`,
         `Sandbox: ${config.sandboxMode}; package policy: ${config.packageInstallPolicy}`,
         `Current plan:\n${state.plan || "(none yet)"}`,

package/src/project.js

@@ -27,6 +27,7 @@ export function projectPaths(projectRoot = process.cwd()) {
   const root = resolveProjectRoot(projectRoot);
   return {
     root,
+    agintiInstructionsPath: path.join(root, "AGINTI.md"),
     controlDir: path.join(root, ".aginti"),
     envPath: path.join(root, ".aginti", ".env"),
     rootEnvPath: path.join(root, ".env"),
@@ -40,6 +41,60 @@ export function projectPaths(projectRoot = process.cwd()) {
   };
 }
 
+export function defaultAgintiInstructions() {
+  return [
+    "# AGINTI.md",
+    "",
+    "Project instructions for AgInTiFlow agents.",
+    "",
+    "Edit this file directly or ask AgInTiFlow to update it during chat. Keep durable project preferences here; keep secrets in `.aginti/.env` instead.",
+    "",
+    "## Project Goals",
+    "",
+    "- Describe what this project is for.",
+    "- Note the main user-facing workflows the agent should preserve.",
+    "",
+    "## Agent Preferences",
+    "",
+    "- Prefer small, inspectable changes over broad rewrites.",
+    "- Read relevant files before editing.",
+    "- Run focused checks when tools and dependencies are available.",
+    "- Keep generated artifacts in project folders with clear names.",
+    "",
+    "## Useful Commands",
+    "",
+    "- Add build, test, lint, preview, or compile commands here.",
+    "",
+    "## Notes",
+    "",
+    "- Add project-specific terminology, style preferences, and known constraints here.",
+    "",
+  ].join("\n");
+}
+
+export async function readProjectInstructions(projectRoot = process.cwd(), { maxBytes = 24_000 } = {}) {
+  const paths = projectPaths(projectRoot);
+  try {
+    const stat = await fsp.stat(paths.agintiInstructionsPath);
+    if (!stat.isFile()) return { exists: false, path: paths.agintiInstructionsPath, content: "", truncated: false };
+    const handle = await fsp.open(paths.agintiInstructionsPath, "r");
+    try {
+      const buffer = Buffer.alloc(Math.min(stat.size, maxBytes));
+      const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+      return {
+        exists: true,
+        path: paths.agintiInstructionsPath,
+        content: buffer.subarray(0, bytesRead).toString("utf8"),
+        truncated: stat.size > maxBytes,
+      };
+    } finally {
+      await handle.close();
+    }
+  } catch {
+    return { exists: false, path: paths.agintiInstructionsPath, content: "", truncated: false };
+  }
+}
+
 export function parseEnvText(text = "") {
   const values = {};
   for (const rawLine of String(text).split(/\r?\n/)) {
@@ -126,6 +181,10 @@ export async function initProject(projectRoot = process.cwd()) {
   await ensureDir(paths.controlDir);
   await ensureDir(paths.notesDir);
   await ensureDir(paths.sessionsDir);
+  await ensureFile(
+    paths.agintiInstructionsPath,
+    defaultAgintiInstructions()
+  );
   await ensureFile(
     paths.controlReadmePath,
     [
@@ -133,6 +192,7 @@ export async function initProject(projectRoot = process.cwd()) {
       "",
       "This folder stores project-local AgInTiFlow configuration.",
       "",
+      "- `../AGINTI.md` stores editable project instructions for CLI and web agents.",
       "- `.env` is ignored and can hold local provider keys.",
       "- `.env.example` documents accepted variable names.",
       "- `.sessions/` at the project root stores CLI and web run history.",
@@ -175,6 +235,7 @@ export async function initProject(projectRoot = process.cwd()) {
   return {
     ok: true,
     projectRoot: paths.root,
+    instructionsPath: paths.agintiInstructionsPath,
     controlDir: paths.controlDir,
     sessionsDir: paths.sessionsDir,
     created,
@@ -318,10 +379,11 @@ export async function npmLatestVersion(packageName = "@lazyingart/agintiflow") {
 export async function doctorReport(projectRoot, packageVersion, config) {
   const paths = projectPaths(projectRoot);
   const keyStatus = providerKeyStatus(projectRoot);
-  const [sessions, dockerStatus, latestVersion] = await Promise.all([
+  const [sessions, dockerStatus, latestVersion, instructions] = await Promise.all([
     listProjectSessions(projectRoot, 8),
     getDockerSandboxStatus(config).catch((error) => ({ ok: false, error: error.message })),
     npmLatestVersion(),
+    readProjectInstructions(projectRoot, { maxBytes: 1 }),
   ]);
 
   return {
@@ -337,6 +399,8 @@ export async function doctorReport(projectRoot, packageVersion, config) {
     },
     project: {
       root: paths.root,
+      instructionsPath: paths.agintiInstructionsPath,
+      instructionsPresent: instructions.exists,
       controlDir: paths.controlDir,
       sessionsDir: paths.sessionsDir,
       sessionDbPath: paths.sessionDbPath,

package/src/task-profiles.js

@@ -3,63 +3,63 @@ export const TASK_PROFILES = {
     id: "auto",
     label: "Auto",
     prompt:
-      "Infer the task type from the user request. For short tasks, use the smallest safe tool sequence that completes the work. For codebase, system, debugging, migration, or multi-language tasks, switch into the engineering loop: inspect, read/search exact context, patch incrementally, run focused checks, repair failures, and summarize changed files plus residual risks.",
+      "Act as the general-purpose AgInTiFlow agent. Infer the task type from the request, then choose the right mix of browser, shell, files, web search, canvas, and sandbox tools. For short tasks, use the smallest safe tool sequence that completes the work. For codebase, writing, website, LaTeX, system, debugging, migration, or multi-language tasks, automatically borrow the relevant specialized profile habits without becoming narrowly constrained.",
     tools: ["browser", "shell", "files", "canvas", "inspect_project"],
   },
   code: {
     id: "code",
     label: "Code writing",
     prompt:
-      "Act like a coding agent across languages: inspect project manifests and conventions, edit workspace files with patches, run useful focused checks, iterate on failures, and report changed files and residual risks.",
+      "Bias toward coding-agent behavior across languages, but remain a general assistant when the task needs docs, shell, web, or design work. Inspect project instructions/manifests/conventions, edit workspace files with patches, run useful focused checks, iterate on failures, and report changed files plus residual risks.",
     tools: ["inspect_project", "files", "shell", "sandbox"],
   },
   "large-codebase": {
     id: "large-codebase",
     label: "Large codebase engineering",
     prompt:
-      "For large or complicated engineering work, behave like a senior coding agent: inspect_project first unless the repo is already known, read AGENTS/README/manifests, locate entry points and tests, make a small explicit change plan, patch in coherent batches, run the narrowest relevant checks first, escalate to broader checks when stable, and summarize files changed, checks, tradeoffs, and remaining risks.",
+      "Bias toward senior large-repo engineering while still answering ordinary side questions. Inspect_project first unless context is already known, read AGINTI/AGENTS/README/manifests, locate entry points and tests, make a small explicit change plan, patch in coherent batches, run the narrowest relevant checks first, escalate to broader checks when stable, and summarize files changed, checks, tradeoffs, and remaining risks.",
     tools: ["inspect_project", "search_files", "read_file", "apply_patch", "shell", "sandbox", "canvas"],
   },
   writing: {
     id: "writing",
     label: "Book/script writing",
     prompt:
-      "Create structured drafts with outlines, sections, and revision notes. Use files for long-form output and canvas for important drafts.",
+      "Bias toward long-form writing quality without refusing adjacent research, code, or formatting tasks. Create structured drafts with outlines, sections, revision notes, and saved files for durable output. Use web search when current sources matter and canvas for important drafts.",
     tools: ["files", "canvas"],
   },
   design: {
     id: "design",
     label: "Design docs",
     prompt:
-      "Produce concise design documents with goals, constraints, options, tradeoffs, implementation steps, and verification criteria.",
+      "Bias toward clear product/engineering design while remaining able to implement or test when asked. Produce concise design documents with goals, constraints, options, tradeoffs, implementation steps, verification criteria, and decision records.",
     tools: ["files", "canvas"],
   },
   python: {
     id: "python",
     label: "Python",
     prompt:
-      "For Python tasks, create small scripts or notebooks as files, prefer virtual environments or Docker for package setup, and run smoke checks when shell is enabled.",
+      "Bias toward Python best practices without ignoring non-Python project context. Inspect pyproject/requirements, create scripts/packages/tests as files, prefer project-local venv/conda/uv or Docker for setup, and run focused smoke checks when shell is enabled.",
     tools: ["files", "shell", "sandbox"],
   },
   shell: {
     id: "shell",
     label: "Shell",
     prompt:
-      "For shell tasks, use allowlisted commands, explain blocked commands, avoid destructive operations, and keep outputs concise.",
+      "Bias toward terminal/system diagnosis and scripting while still using files, web, or docs when useful. Gather evidence first, write reusable scripts when appropriate, follow the configured trust/sandbox policy, and keep command outputs concise.",
     tools: ["shell", "sandbox"],
   },
   node: {
     id: "node",
     label: "Node",
     prompt:
-      "For Node.js tasks, use the local project structure, add tests when useful, and run safe npm/node checks when available.",
+      "Bias toward Node/JavaScript/TypeScript workflows without excluding frontend, backend, docs, or deployment work. Inspect package.json/lockfiles, respect the package manager, add tests when useful, and run safe npm/node checks when available.",
     tools: ["files", "shell", "sandbox"],
   },
   website: {
     id: "website",
     label: "Website testing",
     prompt:
-      "For website/app tasks, create or inspect real site files, preview with workspace preview tools, add local checks when useful, and use the configured sandbox/package policy for dependencies.",
+      "Bias toward real website/app delivery while staying general enough for copy, assets, backend, and tests. Create or inspect real site files, use vivid but tidy UI when designing from scratch, preview with workspace preview tools, add local checks when useful, and use the configured sandbox/package policy for dependencies.",
     tools: ["files", "shell", "canvas", "sandbox"],
   },
   image: {
@@ -73,21 +73,21 @@ export const TASK_PROFILES = {
     id: "aaps",
     label: "AAPS",
     prompt:
-      "For AAPS tasks, recognize .aaps folders and @lazyingart/aaps workflows, keep work project-local, and avoid secrets or publishing.",
+      "Bias toward AAPS workflows while still handling normal project work. Recognize .aaps folders and @lazyingart/aaps conventions, keep work project-local, document assumptions, and avoid secrets or publishing unless explicitly requested.",
     tools: ["files", "shell", "sandbox"],
   },
   latex: {
     id: "latex",
     label: "LaTeX",
     prompt:
-      "For LaTeX/PDF tasks, locate or create source and figures in a subfolder, compile when a TeX toolchain is available, run enough passes for references, and send the PDF through the canvas tunnel. In Docker, use /workspace for project outputs and the persistent Python/conda/tool cache under /aginti-env when setup is needed.",
+      "Bias toward LaTeX/PDF production while still using writing, plotting, code, and web research when needed. Locate or create source and figures in a subfolder, compile when a TeX toolchain is available, run enough passes for references, and send the PDF through the canvas tunnel. In Docker, use /workspace for outputs and /aginti-env for persistent tools when setup is needed.",
     tools: ["files", "shell", "canvas", "sandbox"],
   },
   maintenance: {
     id: "maintenance",
     label: "System maintenance",
     prompt:
-      "For system maintenance and system bugs, diagnose first with read-only evidence, use Docker for broad installs/toolchains when available, generate reversible project-local scripts, follow the configured trust/package policy for host-level changes, and stop with clear next actions if stronger permission is needed.",
+      "Bias toward practical system repair while staying useful for code/docs around the fix. Diagnose first with read-only evidence, use Docker for broad installs/toolchains when available, generate reversible project-local scripts, follow the configured trust/package policy for host-level changes, and stop with clear next actions if stronger permission is needed.",
     tools: ["shell", "sandbox", "files", "inspect_project"],
   },
 };

package/src/workspace-tools.js

@@ -53,6 +53,7 @@ const IMPORTANT_MANIFESTS = new Set([
   "compose.yml",
   "README.md",
   "AGENTS.md",
+  "AGINTI.md",
 ]);
 const SOURCE_DIR_NAMES = new Set(["src", "app", "lib", "packages", "apps", "bin", "scripts", "server", "client", "public", "docs"]);
 const TEST_DIR_NAMES = new Set(["test", "tests", "__tests__", "spec", "specs", "e2e"]);
@@ -279,7 +280,7 @@ async function readJsonFileSafe(absolutePath) {
 
 function recommendedReads(summary) {
   const reads = [];
-  for (const name of ["AGENTS.md", "README.md", "package.json", "pyproject.toml", "Cargo.toml", "go.mod"]) {
+  for (const name of ["AGINTI.md", "AGENTS.md", "README.md", "package.json", "pyproject.toml", "Cargo.toml", "go.mod"]) {
     const match = summary.manifestFiles.find((item) => item.path === name || item.path.endsWith(`/${name}`));
     if (match) reads.push(match.path);
   }
@@ -533,7 +534,7 @@ async function inspectProject(config, args) {
     packageScripts,
     recommendedReads: [],
     engineeringHints: [
-      "Read AGENTS/README/manifests before editing.",
+      "Read AGINTI/AGENTS/README/manifests before editing.",
       "Use search_files to locate symbols and tests, then read exact files.",
       "Use apply_patch for source edits and run the smallest relevant check first.",
       "If a change spans modules, patch in small batches and verify after each batch.",