memoryintel 1.0.0 → 1.0.2

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Persistent, cross-session project memory for AI coding agents.",
-    "version": "1.0.0"
+    "version": "1.0.2"
   },
   "plugins": [
     {
       "name": "memoryintel",
       "source": "./",
       "description": "Persistent project memory for AI coding agents — initialize once, then agents automatically load and update project understanding across sessions.",
-      "version": "1.0.0"
+      "version": "1.0.2"
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "memoryintel",
   "description": "Persistent project memory for AI coding agents — initialize once, then agents automatically load and update project understanding across sessions.",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "author": {
     "name": "Adeesh Sharma",
     "url": "https://github.com/adeeshsharma"

package/README.md

@@ -120,6 +120,37 @@ when something meaningful changes — never a changelog, always a maintained und
 project as it currently is. See `.memoryintel/context/decisions.md` in this very repository for
 the specific design decisions behind that, with rationale.
 
+## Existing projects (not greenfield)
+
+`memoryintel init` scaffolds empty files — fine for a brand-new project, wasteful for one that
+already has real history. Two commands help, and most existing projects want both, in order:
+
+```bash
+memoryintel scan     # read-only: stack + top-level layout, nothing more
+memoryintel import   # write: pulls every real doc in the repo into the matching section
+```
+
+Neither command tries to reverse-engineer architecture from code — no import-graph analysis, no
+git-history mining, no keyword extraction. That's a real judgment task, and this project already
+has a mechanism for judgment: the agent's own accumulated `update` calls as it actually works in
+the repo, exactly like it already works for a greenfield project. These two commands exist only
+to stop session one from flailing, not to front-load understanding they can't honestly derive.
+
+**`scan`** never writes anything — it prints detected stack (`package.json`/`pyproject.toml`/
+`go.mod`/`Cargo.toml`: dependencies, scripts, entry points) and a one-level-deep directory
+listing. That's it. Enough to answer "how do I even run this" without reading the tree cold.
+
+**`import`** walks the whole repo for real documentation — any `.md`/`.html` file, anywhere, not
+just a fixed list of known filenames like `memory-bank/`'s convention. An HTML file only counts
+if it's an actual document (real prose, not a bundled SPA shell — index.html with a mount div and
+a script tag doesn't count). Each document's content is copied verbatim into a `.memoryintel/`
+section chosen by matching keywords in its filename/title (`architecture.md` → `technical/
+architecture.md`, `product-notes.md` → `business/productContext.md`, anything unrecognized still
+lands in `context/projectBrief.md` rather than being silently dropped). Purely mechanical — no
+summarizing, splitting, or interpreting, and memoryintel's own pointer-file boilerplate (in
+`AGENTS.md`/`GEMINI.md`) is filtered out so it's never mistaken for real project content. Safe to
+re-run; already-imported content is skipped, not duplicated.
+
 ## Benchmarks: with vs. without
 
 Measured on a real second project ([distilled-docs](https://github.com/adeeshsharma/distilled-docs),

package/dist/adapters/genericPointer.js

@@ -3,10 +3,19 @@ import { join } from 'node:path';
 const START_MARKER = '<!-- memoryintel:managed:start -->';
 const END_MARKER = '<!-- memoryintel:managed:end -->';
 const POINTER_BLOCK = `${START_MARKER}
-This project uses Memory Intel. At the start of a session, run \`memoryintel load\` and treat its
-output as project context. Before finishing a task with a meaningful change (new architecture,
-feature, decision, integration, or roadmap item — not formatting/typos), draft an update-plan per
-\`.memoryintel/instructions.md\` and run \`memoryintel update\`, without narrating this to the user.
+This project uses Memory Intel (\`.memoryintel/\`) for persistent, cross-session project memory.
+Read \`.memoryintel/instructions.md\` for the full mechanism. Two hard requirements, not optional
+background context:
+
+1. **Session start:** run \`memoryintel load\` before doing anything else and treat its output as
+   real project context, not a formality to skip past.
+2. **Before ending any task that changed project understanding** (new architecture, feature,
+   decision, integration, or roadmap item — not formatting/typos): draft an update-plan and run
+   \`memoryintel update <plan-file>\`. This applies even in a long session covering many sub-tasks —
+   that is exactly when it is easiest to reach the end and have forgotten this step was ever
+   pending. If nothing meaningful changed, skip it; do not skip it just because the task grew long.
+
+Tell the user when you do this — do not do it silently.
 ${END_MARKER}`;
 function upsertPointerBlock(filePath, existingContentIfNew) {
     if (!existsSync(filePath)) {

package/dist/cli.js

@@ -7,6 +7,8 @@ import { runUpdate } from './commands/update.js';
 import { runLoad } from './commands/load.js';
 import { runStatus } from './commands/status.js';
 import { runInit } from './commands/init.js';
+import { runImport } from './commands/import.js';
+import { runScan } from './commands/scan.js';
 import { runCheckStop } from './adapters/claudeCode.js';
 import { runDashboardEnable, runDashboardDisable } from './commands/dashboardToggle.js';
 import { runDaemonStart } from './commands/daemonStart.js';
@@ -14,6 +16,10 @@ export const USAGE = `Usage: memoryintel <command> [options]
 
 Commands:
   init [path]              Initialize .memoryintel/ in the current or given directory
+  scan [path]              Print a quick, no-LLM digest of an existing codebase's stack and
+                           top-level layout - orientation only, not architecture
+  import [path]            Pull every real .md/.html document in the repo (not just
+                           memory-bank/-style files) into the matching .memoryintel/ section
   load [--domain <d>]      Print resolved memory context to stdout
   update <plan.toon|->     Apply an update-plan (file path, or - for stdin)
   status                   Print a human-readable summary of current memory state
@@ -35,6 +41,10 @@ export function dispatch(argv) {
             runInit(target);
             return { exitCode: 0, stdout: `Initialized Memory Intel in ${join(target, '.memoryintel')}\n`, stderr: '' };
         }
+        case 'scan': {
+            const target = argv[1] ? join(process.cwd(), argv[1]) : process.cwd();
+            return { exitCode: 0, stdout: runScan(target), stderr: '' };
+        }
         case 'load': {
             const domainFlagIndex = argv.indexOf('--domain');
             const domain = domainFlagIndex !== -1 ? argv[domainFlagIndex + 1] : undefined;
@@ -90,6 +100,24 @@ async function main() {
             // listening HTTP server, until `memoryintel dashboard disable` sends it SIGTERM.
             return;
         }
+        if (command === 'import') {
+            const root = findMemoryIntelRoot(process.cwd());
+            if (!root) {
+                process.stderr.write('No .memoryintel/ found. Run `memoryintel init` first.\n');
+                process.exitCode = 1;
+                return;
+            }
+            const targetDir = argv[1] ? join(process.cwd(), argv[1]) : process.cwd();
+            const result = await runImport(root, targetDir);
+            if (result.sourcesFound.length === 0) {
+                process.stdout.write('No brownfield sources found (looked for memory-bank/, ARCHITECTURE.md, README.md).\n');
+            }
+            else {
+                process.stdout.write(`Sources found: ${result.sourcesFound.join(', ')}\nApplied: ${result.applied.join(', ') || '(none)'}\nSkipped: ${result.skipped.join(', ') || '(none)'}\n`);
+            }
+            process.exitCode = 0;
+            return;
+        }
         if (command === 'update') {
             const root = findMemoryIntelRoot(process.cwd());
             if (!root) {

package/dist/commands/import.js

@@ -0,0 +1,76 @@
+import { relative, sep } from 'node:path';
+import { runUpdate } from './update.js';
+import { encodeToonTable } from '../core/toon.js';
+import { walkFiles, findDocuments } from '../core/repoScan.js';
+// relative() returns backslash-separated paths on Windows. These labels get baked into
+// permanent memory content (the `reason` field, the annotate() header) alongside every other
+// file reference in this project, which is always forward-slash (e.g. `technical/architecture.md`)
+// - a Windows-only backslash would be a visible, permanent inconsistency in stored memory, not
+// just a display quirk. Same class of bug already hit and fixed elsewhere in this codebase
+// (assertSafePath, the compression git-clean check) - normalize once, right at the source.
+function toPosixRelative(targetDir, absPath) {
+    return relative(targetDir, absPath).split(sep).join('/');
+}
+// Ordered, first-match-wins keyword -> target mapping. Deliberately just keyword matching on a
+// document's filename + extracted title, not any real understanding of its content - the general
+// replacement for hardcoding a table of known filenames (memory-bank's convention happens to
+// fall out of this for free: "productContext.md" matches "product", "systemPatterns.md" matches
+// "pattern", with no special-casing needed), generalized to any document anywhere in the repo,
+// under any naming convention.
+const ROUTES = [
+    { keywords: ['architecture', 'design'], file: 'technical/architecture.md', section: 'Overview' },
+    { keywords: ['pattern'], file: 'technical/patterns.md', section: 'Design Patterns' },
+    { keywords: ['tech', 'stack'], file: 'technical/techContext.md', section: 'Stack' },
+    { keywords: ['integration'], file: 'technical/integrations.md', section: 'External Services' },
+    { keywords: ['infra', 'deploy'], file: 'technical/infrastructure.md', section: 'Deployment' },
+    { keywords: ['product'], file: 'business/productContext.md', section: 'Product Overview' },
+    { keywords: ['roadmap'], file: 'business/roadmap.md', section: 'Now' },
+    { keywords: ['stakeholder', 'team'], file: 'business/stakeholders.md', section: 'Team' },
+    { keywords: ['market'], file: 'business/marketContext.md', section: 'Market Overview' },
+    { keywords: ['progress', 'status'], file: 'context/progress.md', section: 'Status' },
+    { keywords: ['active', 'focus', 'current'], file: 'context/activeContext.md', section: 'Current Focus' },
+    { keywords: ['decision'], file: 'context/decisions.md', section: 'Decisions Log' },
+    { keywords: ['learn'], file: 'context/learnings.md', section: 'Learnings' },
+    { keywords: ['objective', 'goal'], file: 'context/objectives.md', section: 'Objectives' },
+    { keywords: ['hypothes'], file: 'research/hypotheses.md', section: 'Open Hypotheses' },
+    { keywords: ['finding', 'research'], file: 'research/findings.md', section: 'Key Findings' },
+    { keywords: ['reference'], file: 'research/references.md', section: 'Sources' },
+    { keywords: ['readme', 'brief', 'overview'], file: 'context/projectBrief.md', section: 'Overview' }
+];
+// Anything matching no keyword still lands somewhere a human/agent will see it, rather than
+// being silently dropped for not fitting a known bucket.
+const DEFAULT_ROUTE = { file: 'context/projectBrief.md', section: 'Overview' };
+function route(doc, targetDir) {
+    const haystack = `${toPosixRelative(targetDir, doc.path)} ${doc.title}`.toLowerCase();
+    for (const r of ROUTES) {
+        if (r.keywords.some((k) => haystack.includes(k)))
+            return { file: r.file, section: r.section };
+    }
+    return DEFAULT_ROUTE;
+}
+function annotate(content, sourceLabel) {
+    const today = new Date().toISOString().slice(0, 10);
+    return `_Imported verbatim from \`${sourceLabel}\` on ${today} — not yet re-filed into per-section structure; treat as raw source material for the next real update._\n\n${content.trim()}`;
+}
+export async function runImport(root, targetDir) {
+    const files = walkFiles(targetDir);
+    const docs = findDocuments(targetDir, files);
+    if (docs.length === 0) {
+        return { applied: [], skipped: [], sourcesFound: [] };
+    }
+    const sourcesFound = docs.map((d) => toPosixRelative(targetDir, d.path));
+    const candidates = docs.map((doc) => {
+        const target = route(doc, targetDir);
+        const label = toPosixRelative(targetDir, doc.path);
+        return {
+            file: target.file,
+            action: 'append',
+            section: target.section,
+            content: annotate(doc.content, label),
+            reason: `Brownfield import from ${label}`
+        };
+    });
+    const planText = encodeToonTable(candidates);
+    const { applied, skipped } = await runUpdate(root, planText);
+    return { applied, skipped, sourcesFound };
+}

package/dist/commands/init.js

@@ -6,6 +6,26 @@ const INSTRUCTIONS_TEMPLATE = `# Memory Intel Instructions
 
 This project uses Memory Intel. Read this file at the start of every session.
 
+## First session on an existing project
+If \`.memoryintel/\` was just initialized on a project that already has real history (not a fresh
+scaffold), run both before anything else - neither tries to reverse-engineer architecture, so
+neither is a substitute for the other:
+
+1. \`memoryintel import\` walks the whole repo for real documentation (any \`.md\`/\`.html\` file,
+   not a fixed list of known filenames) and mechanically copies each one's content verbatim into
+   the \`.memoryintel/\` section its filename/title best matches. Deterministic, no judgment. Its
+   output is raw and unfiled by design; treat it as source material to read and properly re-file
+   yourself, not as finished memory.
+2. \`memoryintel scan\` never writes anything - it prints detected stack and a one-level-deep
+   directory listing, nothing more. Enough to answer "how do I run this", not an attempt at
+   understanding the codebase's architecture.
+
+Real understanding - architecture, patterns, why things are built the way they are - is not
+something either command can honestly derive. It builds the same way it already does on a
+greenfield project: through your own judgment as you actually work here, one real \`update\` at a
+time. Both commands are safe to run more than once - \`import\`'s already-imported content is
+skipped, not duplicated, and \`scan\` never writes anything at all.
+
 ## Session start
 Run \`memoryintel load [--domain technical|business|research]\` and treat its output as project context.
 Its manifest reports each loaded file's \`lines\`, \`ceiling\`, and \`status\` (\`over\`/\`under\`) — see
@@ -38,6 +58,24 @@ on a real project: a "known limitation, deliberately left unfixed" entry was sti
 \`currentMentalModel.md\`, but never reconciled against the older, now-wrong decisions entry right
 next to it.
 
+## Committing \`.memoryintel/\` itself
+\`.memoryintel/\` is a normal, git-committed part of the project — \`memoryintel update\` only writes
+files to disk, it never runs git for you. After a successful \`update\`, commit \`.memoryintel/\`'s
+changes yourself, ideally in the same commit as (or immediately after) whatever code change
+prompted the update, so it travels with the same commit/PR automatically instead of being left
+behind as an uncommitted diff.
+
+This matters most in a git worktree, a container, or any other isolated checkout: an uncommitted
+\`.memoryintel/\` change only exists in that one working directory. Merging a feature branch's PR and
+pulling the primary checkout up to date only brings memory updates along if they were actually
+committed first, the same as any other file — there is nothing worktree-specific about the
+mechanism itself, only that a worktree's own uncommitted state is easier to lose track of, since it
+is invisible everywhere else once the session ends and that directory stops being looked at. Found
+on a real project: a full feature built end-to-end in a worktree, with real, meaningful
+architecture changes throughout, reached a merged PR with \`.memoryintel/\` never once updated or
+committed — not because updating was hard, but because nothing in the session ever came back to it
+before the worktree's job was considered done.
+
 ## Compaction
 A file marked \`status: over\` in \`load\`'s manifest has grown past its configured line ceiling.
 This is a signal, not a command — compact it only when it's a sensible moment to (the same

package/dist/commands/scan.js

@@ -0,0 +1,28 @@
+import { detectStack, listTopLevel } from '../core/repoScan.js';
+// A quick, deterministic, no-LLM digest of an existing codebase's stack and setup - the
+// brownfield equivalent of `load`'s first orientation, nothing more. Deliberately does not try
+// to infer architecture (no import graphs, no git-churn ranking, no keyword extraction): that's
+// real judgment, and this project already has a mechanism for judgment - the agent's own
+// accumulated `update` calls as it actually works in the repo, same as it already works for a
+// greenfield project. scan's only job is to stop session one from flailing on "how do I even run
+// this", not to front-load understanding a scan can't actually derive honestly.
+export function runScan(targetDir) {
+    const lines = [];
+    const stack = detectStack(targetDir);
+    lines.push('=== Detected Stack ===');
+    lines.push(stack.manifests.length > 0 ? `Manifests: ${stack.manifests.join(', ')}` : '(no recognized manifest found)');
+    if (stack.dependencies.length > 0) {
+        const shown = stack.dependencies.slice(0, 30);
+        const suffix = stack.dependencies.length > 30 ? ` (+${stack.dependencies.length - 30} more)` : '';
+        lines.push(`Dependencies: ${shown.join(', ')}${suffix}`);
+    }
+    if (Object.keys(stack.scripts).length > 0) {
+        lines.push(`Scripts: ${Object.entries(stack.scripts).map(([k, v]) => `${k}="${v}"`).join(', ')}`);
+    }
+    if (stack.entryPoints.length > 0)
+        lines.push(`Entry points: ${stack.entryPoints.join(', ')}`);
+    lines.push('', '=== Top-Level Layout ===');
+    const topLevel = listTopLevel(targetDir);
+    lines.push(topLevel.length > 0 ? topLevel.join(', ') : '(empty directory)');
+    return lines.join('\n') + '\n';
+}

package/dist/core/repoScan.js

@@ -0,0 +1,250 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join, extname } from 'node:path';
+// Common vendor/build/cache directories across the ecosystems this scans (JS/TS, Python, Go,
+// Rust). Not full .gitignore parsing - a real ignore-file parser is its own project, and this
+// hardcoded list already keeps a scan quick on the repos it's meant for. Missing a project's own
+// unusual output dir just means a few extra files get walked, not a correctness bug.
+// `.memoryintel` is excluded deliberately, not an oversight: it's this tool's own bookkeeping
+// (constantly-churning JSON/event logs, and markdown that's *output*, not source material) -
+// including it here would make a scan review its own scratch state instead of the actual project.
+export const IGNORED_DIRS = new Set([
+    'node_modules', '.git', 'dist', 'build', 'out', '.next', '.nuxt', '.svelte-kit',
+    'target', 'vendor', '__pycache__', '.venv', 'venv', 'env', 'coverage', '.cache',
+    '.turbo', '.parcel-cache', '.pytest_cache', '.mypy_cache', '.idea', '.vscode', '.memoryintel'
+]);
+// Safety cap so a scan stays "quick" even pointed at an enormous or pathologically deep tree.
+const MAX_FILES = 20000;
+// Every file under targetDir, skipping IGNORED_DIRS and symlinks (symlinks risk cycles and can
+// point outside the repo entirely - neither is a case worth handling for a quick scan). Returns
+// absolute paths.
+export function walkFiles(targetDir) {
+    const results = [];
+    function visit(dir) {
+        if (results.length >= MAX_FILES)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (results.length >= MAX_FILES)
+                return;
+            if (entry.isSymbolicLink())
+                continue;
+            if (entry.isDirectory()) {
+                if (IGNORED_DIRS.has(entry.name))
+                    continue;
+                visit(join(dir, entry.name));
+            }
+            else if (entry.isFile()) {
+                results.push(join(dir, entry.name));
+            }
+        }
+    }
+    visit(targetDir);
+    return results;
+}
+// A single level deep, not recursive - "repo/project setup" means "what's here", not a full
+// tree. Directories are listed with a trailing slash so the shape is legible at a glance.
+export function listTopLevel(targetDir) {
+    let entries;
+    try {
+        entries = readdirSync(targetDir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((e) => !(e.isDirectory() && IGNORED_DIRS.has(e.name)))
+        .map((e) => (e.isDirectory() ? `${e.name}/` : e.name))
+        .sort();
+}
+function readJsonSafe(path) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+// Extracts every quoted string or `key =`/`key = "` entry between a section header and the next
+// `[` - good enough to list dependency names out of TOML without pulling in a TOML parser
+// dependency this project has none of today. Not a real TOML parser: won't handle inline
+// tables or multi-line arrays split across many lines with comments in between.
+function extractTomlSectionKeys(text, sectionHeader) {
+    const startIdx = text.indexOf(sectionHeader);
+    if (startIdx === -1)
+        return [];
+    const afterHeader = text.slice(startIdx + sectionHeader.length);
+    const nextSectionIdx = afterHeader.search(/\n\[/);
+    const body = nextSectionIdx === -1 ? afterHeader : afterHeader.slice(0, nextSectionIdx);
+    const keys = [];
+    for (const line of body.split('\n')) {
+        const match = /^\s*"?([\w.-]+)"?\s*=/.exec(line);
+        if (match)
+            keys.push(match[1]);
+    }
+    return keys;
+}
+function extractQuotedStrings(text) {
+    const matches = text.matchAll(/["']([^"'\s]+)["']/g);
+    return [...matches].map((m) => m[1]);
+}
+export function detectStack(targetDir) {
+    const manifests = [];
+    const dependencies = new Set();
+    const scripts = {};
+    const entryPoints = [];
+    const pkgPath = join(targetDir, 'package.json');
+    if (existsSync(pkgPath)) {
+        const pkg = readJsonSafe(pkgPath);
+        if (pkg) {
+            manifests.push('package.json');
+            for (const dep of Object.keys(pkg.dependencies ?? {}))
+                dependencies.add(dep);
+            for (const dep of Object.keys(pkg.devDependencies ?? {}))
+                dependencies.add(dep);
+            Object.assign(scripts, pkg.scripts ?? {});
+            if (typeof pkg.main === 'string')
+                entryPoints.push(pkg.main);
+            if (typeof pkg.bin === 'string')
+                entryPoints.push(pkg.bin);
+            else if (pkg.bin && typeof pkg.bin === 'object')
+                entryPoints.push(...Object.values(pkg.bin));
+        }
+    }
+    const reqPath = join(targetDir, 'requirements.txt');
+    if (existsSync(reqPath)) {
+        manifests.push('requirements.txt');
+        for (const rawLine of readFileSync(reqPath, 'utf-8').split('\n')) {
+            const line = rawLine.split('#')[0].trim();
+            if (!line)
+                continue;
+            const name = line.split(/[=<>~!;\[]/)[0].trim();
+            if (name)
+                dependencies.add(name);
+        }
+    }
+    const pyprojectPath = join(targetDir, 'pyproject.toml');
+    if (existsSync(pyprojectPath)) {
+        manifests.push('pyproject.toml');
+        const text = readFileSync(pyprojectPath, 'utf-8');
+        const projectDepsMatch = /dependencies\s*=\s*\[([\s\S]*?)\]/.exec(text);
+        if (projectDepsMatch) {
+            for (const dep of extractQuotedStrings(projectDepsMatch[1])) {
+                dependencies.add(dep.split(/[=<>~!\s]/)[0]);
+            }
+        }
+        for (const dep of extractTomlSectionKeys(text, '[tool.poetry.dependencies]')) {
+            if (dep !== 'python')
+                dependencies.add(dep);
+        }
+    }
+    const goModPath = join(targetDir, 'go.mod');
+    if (existsSync(goModPath)) {
+        manifests.push('go.mod');
+        const text = readFileSync(goModPath, 'utf-8');
+        for (const match of text.matchAll(/^\s*([\w.\-/]+\.[\w.\-/]+)\s+v[\d.]/gm))
+            dependencies.add(match[1]);
+    }
+    const cargoPath = join(targetDir, 'Cargo.toml');
+    if (existsSync(cargoPath)) {
+        manifests.push('Cargo.toml');
+        const text = readFileSync(cargoPath, 'utf-8');
+        for (const dep of extractTomlSectionKeys(text, '[dependencies]'))
+            dependencies.add(dep);
+    }
+    return { manifests, dependencies: [...dependencies], scripts, entryPoints };
+}
+function extractMarkdownTitle(text) {
+    const h1 = /^#\s+(.+)$/m.exec(text);
+    if (h1)
+        return h1[1].trim();
+    const firstLine = text.split('\n').map((l) => l.trim()).find((l) => l.length > 0);
+    return firstLine ? firstLine.replace(/^#+\s*/, '').slice(0, 80) : '(untitled)';
+}
+function extractHtmlTitle(text) {
+    const title = /<title[^>]*>([\s\S]*?)<\/title>/i.exec(text);
+    if (title)
+        return title[1].replace(/<[^>]+>/g, '').trim().slice(0, 80);
+    const h1 = /<h1[^>]*>([\s\S]*?)<\/h1>/i.exec(text);
+    if (h1)
+        return h1[1].replace(/<[^>]+>/g, '').trim().slice(0, 80);
+    return '(untitled)';
+}
+// SPA shells (a React/Vue/etc. app's index.html) are markup with almost no prose: a mount div
+// and a script tag. A real document is prose-heavy. Neither signal alone is reliable (a tiny
+// real doc could dip under the text threshold; a doc-heavy landing page could avoid the mount-div
+// markers) but together they cover the common cases without needing to know any framework by name.
+const SPA_SHELL_MARKERS = /id=["'](root|app|__next|__nuxt)["']/i;
+const MIN_DOCUMENT_TEXT_LENGTH = 150;
+function visibleText(html) {
+    return html
+        .replace(/<script[\s\S]*?<\/script>/gi, ' ')
+        .replace(/<style[\s\S]*?<\/style>/gi, ' ')
+        .replace(/<[^>]+>/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+export function isDocumentHtml(html) {
+    if (SPA_SHELL_MARKERS.test(html))
+        return false;
+    return visibleText(html).length >= MIN_DOCUMENT_TEXT_LENGTH;
+}
+// True if anything survives once every heading line is stripped out - a file that's only
+// headings (a bare `init` starter section, or a title-only stub) has no actual information.
+function hasMarkdownBody(content) {
+    return content
+        .split('\n')
+        .filter((line) => !/^#+\s/.test(line.trim()))
+        .some((line) => line.trim().length > 0);
+}
+const DOC_EXTENSIONS = new Set(['.md', '.markdown', '.html', '.htm']);
+// The genericPointer adapter (src/adapters/genericPointer.ts) upserts this managed block into
+// AGENTS.md/GEMINI.md - it's memoryintel's own boilerplate, not project documentation. A file
+// that already had real content keeps it and the block is just noise mixed in; a fresh stub file
+// created by `init` with nothing but this block has zero real information and must not be
+// imported as if it described the project (worst case: a brand-new stub's entire content is
+// "this project uses Memory Intel, run `memoryintel load`", which would land in projectBrief.md
+// looking like the project's own description).
+const MANAGED_BLOCK_PATTERN = /<!-- memoryintel:managed:start -->[\s\S]*?<!-- memoryintel:managed:end -->/g;
+// Every real document (not app markup, not memoryintel's own managed content) anywhere under
+// targetDir - the general replacement for hardcoding a table of known filenames like
+// memory-bank's convention. A markdown file is always a document (there's no equivalent "app
+// shell" concept for markdown); an HTML file has to pass isDocumentHtml first.
+export function findDocuments(targetDir, files) {
+    const results = [];
+    for (const file of files) {
+        const ext = extname(file).toLowerCase();
+        if (!DOC_EXTENSIONS.has(ext))
+            continue;
+        let content;
+        try {
+            content = readFileSync(file, 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        content = content.replace(MANAGED_BLOCK_PATTERN, '').trim();
+        if (!content)
+            continue;
+        if (ext === '.html' || ext === '.htm') {
+            if (!isDocumentHtml(content))
+                continue;
+            results.push({ path: file, title: extractHtmlTitle(content), content: visibleText(content) });
+        }
+        else if (!hasMarkdownBody(content)) {
+            // A file that's nothing but a heading (a bare `init` starter section, or an AGENTS.md
+            // stub reduced to just its "# Project Instructions" title once the managed block above is
+            // stripped) has no real information - importing it would be pure noise, not source material.
+            continue;
+        }
+        else {
+            results.push({ path: file, title: extractMarkdownTitle(content), content });
+        }
+    }
+    return results;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memoryintel",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Persistent, cross-session project memory for AI coding agents.",
   "type": "module",
   "bin": {

package/skills/memoryintel/SKILL.md

@@ -39,6 +39,10 @@ Usage: memoryintel <command> [options]
 
 Commands:
   init [path]              Initialize .memoryintel/ in the current or given directory
+  scan [path]              Print a quick, no-LLM digest of an existing codebase's stack and
+                           top-level layout - orientation only, not architecture
+  import [path]            Pull every real .md/.html document in the repo (not just
+                           memory-bank/-style files) into the matching .memoryintel/ section
   load [--domain <d>]      Print resolved memory context to stdout
   update <plan.toon|->     Apply an update-plan (file path, or - for stdin)
   status                   Print a human-readable summary of current memory state