feat(config): add codegraph.json "deprioritize" for ranking-only path down-weighting (#982) (#1463)

* feat(config): add codegraph.json "deprioritize" for ranking-only path down-weighting

matchesNonProductionDir hardcodes example/sample/fixture/benchmark/demo,
so a peripheral tree only the project knows about — optional-skills/,
scripts/ — gets no de-prioritization. When helpers there carry generic
symbol names, an exact name match hands them a large bonus and they crowd
out the product code that answers the query (#982).

deprioritize is the RANKING counterpart to exclude: those paths stay
indexed and findable, they just stop outranking first-party code. It is
deliberately distinct from the corpus-frequency discount, which keys on a
name being common and is near-inert on #982's own repro where only two
symbols are named usage.

The -15 path penalty alone is not enough, and measuring showed why: on
that repro a usage() helper sits at 74.8 against 51.2 for the top product
symbol, so -15 lands at 59.8 and still leads. The path penalty is additive
and the name bonus it must counter is additive and larger. A de-prioritized
path is saying its symbol NAMES are not the answer, so the exact-name bonus
is damped to 0.25x there as well — damped, not zeroed, so the tree still
ranks when it genuinely is what you asked for.

Refs #982

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SKXAJMrVrdHS5Uco6ABtky

* fix(config): read deprioritize lazily and apply it in explore too

Review of the first cut found two real defects.

The matcher was built once in wireLayers(), which runs only from the
constructor and from reopenIfReplaced(). The MCP server keeps one
CodeGraph per project root alive for its whole lifetime, so editing
codegraph.json appeared to do nothing until the process restarted --
exclude and include do not behave that way. The predicate now reads
loadDeprioritizePatterns() per call (mtime-cached, one stat) and memoizes
the compiled matcher on the pattern array's identity. A regression test
writes the config after opening the project and fails on the old code.

Explore passed no matcher to scorePathRelevance at either of its two call
sites, so the setting only half-applied -- and #982's reproduction rows
B, C and D are all codegraph explore, which made this the surface the
issue actually reports on. Both sites now pass it.

Explore's hard early-continue filters and its non-production budget cap
are deliberately NOT joined: those REMOVE content, and deprioritize is a
ranking lever by definition. README narrowed accordingly -- it previously
claimed this extends the built-in list, which overstated it.

Also from review: scorePathRelevance takes a boolean rather than a
predicate (the caller already evaluated it, and it was being invoked
twice per result), the predicate body is exception-guarded so a bad path
can never take a search down, the misplaced const moved out from between
imports, two vacuous test assertions tightened, and tests added for the
single-penalty invariant, the deliberate isTestQuery asymmetry, and a
query that genuinely targets the de-prioritized tree.

Refs #982

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SKXAJMrVrdHS5Uco6ABtky

* fix(search): derive the deprioritize name-bonus damping instead of picking it (#982)

The 0.25 scale was a guess. On a 62k-node django index it measurably breaks
the "discount, don't erase" rule the lever is built on: exact-name queries for
symbols that live only in the de-prioritized tree (child, parent, method) fall
behind mere prefix matches (children, all_parents, method_decorator).

The prefix arm of nameMatchBonus tops out below 40, and a de-prioritized node
also takes the -15 path penalty, so 80 * SCALE - 15 > 40 is the bound that
keeps a damped exact match ahead of a prefix match at any corpus shape. 0.75
clears it; crowd-out removal is nearly identical to 0.5 (39 vs 40 of 88
peripheral top-10 slots cleared on django), so the deeper discount bought
almost nothing and cost the invariant.

Two tests pin the bound, including one that fails at the old 0.25.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

README.md

@@ -669,6 +669,26 @@ CodeGraph discovers those files off disk, overriding `.gitignore`, on index,
 sync, and watch. An explicit `exclude` still wins, and built-in skips
 (`node_modules`, `dist`, `.git`) are never re-included.
 
+Sometimes a directory shouldn't leave the index — you still want to find things
+in it — it just shouldn't *outrank* your real code. A `scripts/` or
+`optional-skills/` tree whose helpers use generic names (`usage`, `status`,
+`run`) can win on an exact name match and crowd out the product code that
+actually answers the query. Name those trees under `deprioritize`:
+
+```json
+{
+  "deprioritize": ["optional-skills/", "scripts/"]
+}
+```
+
+This is the ranking counterpart to `exclude`: those paths stay indexed and
+findable — searching for them directly still works — they just stop winning
+against first-party code. It applies to `query` / `search` and to `explore`'s
+ranking. It is *not* a filter: unlike the built-in `example/`, `sample/`,
+`fixture/`, `benchmark/` and `demo/` handling — which also drops those files
+from some result sets outright — `deprioritize` only ever changes rank. Reach
+for `exclude` when you want something gone.
+
 ### Custom file extensions
 
 If your project uses a non-standard extension for a [supported

__tests__/deprioritize-config.test.ts

@@ -0,0 +1,280 @@
+/**
+ * `codegraph.json` → `deprioritize` — user-extensible ranking de-prioritization (#982).
+ *
+ * `matchesNonProductionDir` hardcodes example/sample/fixture/benchmark/demo, so a
+ * peripheral tree only the project knows about — `optional-skills/`, `scripts/` —
+ * gets no de-prioritization. When helpers in such a tree carry generic symbol
+ * names, an exact name match hands them a large bonus and they crowd out the
+ * product code that actually answers the query.
+ *
+ * This is the *ranking* half of #982, deliberately distinct from the corpus-
+ * frequency discount: that one keys on a name being COMMON, and is near-inert on
+ * #982's own 8-file repro where only two symbols are named `usage`. The fixture
+ * here IS that repro, which is the point — the two levers cover different shapes.
+ *
+ * It is also distinct from `exclude`, which is a recall lever. De-prioritized
+ * paths stay indexed and findable; they just stop winning. Locked below.
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { CodeGraph } from '../src';
+import { initGrammars, loadAllGrammars } from '../src/extraction/grammars';
+import { loadDeprioritizePatterns } from '../src/project-config';
+import { nameMatchBonus, scorePathRelevance } from '../src/search/query-utils';
+import { DEPRIORITIZED_NAME_BONUS_SCALE } from '../src/db/queries';
+
+const QUERY = 'desktop status bar context window usage';
+
+/** #982's minimal reproduction layout. */
+function writeRepro(root: string): void {
+  const mk = (rel: string, content: string) => {
+    const p = path.join(root, rel);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, content);
+  };
+
+  // Product code. No symbol here is literally named `usage`.
+  mk(
+    'apps/desktop/statusbar/StatusBar.ts',
+    [
+      'export class DesktopStatusBar {',
+      '  render(): string { return this.refresh(); }',
+      '  refresh(): string { return "status bar"; }',
+      '  mount(): void {}',
+      '}',
+    ].join('\n')
+  );
+  mk(
+    'apps/desktop/statusbar/StatusBarController.ts',
+    [
+      "import { DesktopStatusBar } from './StatusBar';",
+      'export class StatusBarController {',
+      '  constructor(private readonly bar: DesktopStatusBar) {}',
+      '  show(): string { return this.bar.render(); }',
+      '}',
+    ].join('\n')
+  );
+  mk(
+    'apps/desktop/context/ContextWindowMeter.ts',
+    [
+      'export class ContextWindowMeter {',
+      '  read(): number { return this.recompute(); }',
+      '  recompute(): number { return estimateTokens("context window"); }',
+      '}',
+      'export function estimateTokens(text: string): number { return text.length; }',
+    ].join('\n')
+  );
+  mk(
+    'apps/desktop/context/format.ts',
+    'export function formatTokens(n: number): string { return `${n} tokens`; }\n'
+  );
+  mk('gateway/server/server.ts', 'export function startServer(): void {}\n');
+  mk('packages/core/util/strings.ts', 'export function slugify(s: string): string { return s; }\n');
+
+  // The peripheral tree: two standalone helpers, each with a module-level `usage`.
+  for (const skill of ['bodyfat', 'nutrition']) {
+    mk(
+      `optional-skills/${skill}/scripts/${skill}_calc.ts`,
+      ['export function usage(): void {', `  console.log("usage: ${skill}_calc [options]");`, '}'].join('\n')
+    );
+  }
+}
+
+const isHelper = (r: { node: { name: string; filePath: string } }): boolean =>
+  r.node.name.toLowerCase() === 'usage' && r.node.filePath.includes('optional-skills');
+
+describe('codegraph.json deprioritize — parsing', () => {
+  let dir: string;
+
+  beforeAll(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-deprio-cfg-'));
+  });
+
+  afterAll(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  const write = (config: unknown): string => {
+    const sub = fs.mkdtempSync(path.join(dir, 'p-'));
+    fs.writeFileSync(path.join(sub, 'codegraph.json'), JSON.stringify(config));
+    return sub;
+  };
+
+  it('defaults to empty with no config file', () => {
+    const sub = fs.mkdtempSync(path.join(dir, 'none-'));
+    expect(loadDeprioritizePatterns(sub)).toEqual([]);
+  });
+
+  it('keeps gitignore-style patterns verbatim, trimmed', () => {
+    const sub = write({ deprioritize: ['optional-skills/', '  tools/gen  ', 'vendor/**'] });
+    expect(loadDeprioritizePatterns(sub)).toEqual(['optional-skills/', 'tools/gen', 'vendor/**']);
+  });
+
+  it('warns-and-skips a non-array value instead of throwing', () => {
+    const sub = write({ deprioritize: 'optional-skills/' });
+    expect(loadDeprioritizePatterns(sub)).toEqual([]);
+  });
+
+  it('drops blank and non-string entries, keeping the rest', () => {
+    const sub = write({ deprioritize: ['optional-skills/', '', 42, '   ', 'scripts/'] });
+    expect(loadDeprioritizePatterns(sub)).toEqual(['optional-skills/', 'scripts/']);
+  });
+
+  it('does not disturb the other config keys', () => {
+    const sub = write({ deprioritize: ['optional-skills/'], exclude: ['static/'] });
+    expect(loadDeprioritizePatterns(sub)).toEqual(['optional-skills/']);
+  });
+});
+
+describe('#982 minimal repro — ranking with and without deprioritize', () => {
+  let baseDir: string;
+  let cfgDir: string;
+  let baseCg: CodeGraph;
+  let cfgCg: CodeGraph;
+
+  beforeAll(async () => {
+    await initGrammars();
+    await loadAllGrammars();
+
+    baseDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-deprio-base-'));
+    writeRepro(baseDir);
+    baseCg = CodeGraph.initSync(baseDir);
+    await baseCg.indexAll();
+
+    cfgDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-deprio-on-'));
+    writeRepro(cfgDir);
+    fs.writeFileSync(
+      path.join(cfgDir, 'codegraph.json'),
+      JSON.stringify({ deprioritize: ['optional-skills/'] }, null, 2)
+    );
+    cfgCg = CodeGraph.initSync(cfgDir);
+    await cfgCg.indexAll();
+  }, 180_000);
+
+  afterAll(() => {
+    baseCg?.destroy();
+    cfgCg?.destroy();
+    for (const d of [baseDir, cfgDir]) if (d) fs.rmSync(d, { recursive: true, force: true });
+  });
+
+  it('control: without the config the usage() helpers still take the top ranks', () => {
+    // This is the status quo the issue reports, and the shape the corpus-frequency
+    // discount cannot fix (only two symbols are named `usage` here, so it is rare).
+    const results = baseCg.searchNodes(QUERY, { limit: 20 });
+    expect(results.length).toBeGreaterThanOrEqual(2);
+    expect(results.slice(0, 2).every(isHelper)).toBe(true);
+  });
+
+  it('with deprioritize, product code outranks the peripheral helpers', () => {
+    const results = cfgCg.searchNodes(QUERY, { limit: 20 });
+    const firstHelper = results.findIndex(isHelper);
+    const firstProduct = results.findIndex((r) => r.node.filePath.includes('apps/desktop'));
+    expect(firstProduct).toBeGreaterThanOrEqual(0);
+    expect(firstHelper === -1 || firstProduct < firstHelper).toBe(true);
+  });
+
+  it('is a ranking lever, not exclude: the helpers stay indexed and findable', () => {
+    // The whole point of keeping this distinct from `exclude` — recall is intact.
+    expect(cfgCg.getNodesByName('usage').length).toBe(2);
+    const direct = cfgCg.searchNodes('usage', { limit: 20 });
+    expect(direct.some(isHelper)).toBe(true);
+  });
+
+  it('leaves paths outside the patterns alone', () => {
+    // gateway/ and packages/ are not named, so their scores must not move.
+    const score = (cg: CodeGraph, file: string): number | undefined =>
+      cg.searchNodes('slugify', { limit: 20 }).find((r) => r.node.filePath.includes(file))?.score;
+    const baseline = score(baseCg, 'packages/core/util/strings.ts');
+    expect(baseline).toBeDefined();
+    expect(score(cfgCg, 'packages/core/util/strings.ts')).toBe(baseline);
+  });
+
+  it('a query that genuinely targets the tree still ranks it, competitor present', () => {
+    // The "discount, don't erase" edge case #982 calls out. `bodyfat_calc` lives
+    // only in the de-prioritized tree; a query naming it must still find it
+    // first, even with product code competing for the same terms.
+    const results = cfgCg.searchNodes('bodyfat calc usage', { limit: 20 });
+    expect(results.length).toBeGreaterThan(0);
+    expect(results[0].node.filePath).toContain('optional-skills/bodyfat');
+  });
+
+  it('explore ranking honours the setting, not just search', () => {
+    // #982's reproduction rows B/C/D are all `codegraph explore`. Explore ranks
+    // through its own path scorer as well as through searchNodes, so a
+    // search-only fix would leave the reported surface unchanged.
+    const matcher = (cfgCg as unknown as { queries: { getDeprioritizedPathMatcher(): ((p: string) => boolean) | undefined } })
+      .queries.getDeprioritizedPathMatcher();
+    expect(matcher).toBeDefined();
+    expect(matcher!('optional-skills/bodyfat/scripts/bodyfat_calc.ts')).toBe(true);
+    expect(matcher!('apps/desktop/statusbar/StatusBar.ts')).toBe(false);
+  });
+
+  it('picks up a config written after the project was opened', async () => {
+    // wireLayers runs once per open, so a matcher captured there would freeze
+    // at open time — and the MCP server keeps one CodeGraph per root alive for
+    // its whole lifetime, which would make an edited config look like a no-op.
+    const late = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-deprio-late-'));
+    writeRepro(late);
+    const cg = CodeGraph.initSync(late);
+    try {
+      await cg.indexAll();
+      const before = cg.searchNodes(QUERY, { limit: 20 });
+      expect(before.length).toBeGreaterThanOrEqual(2);
+      expect(before.slice(0, 2).every(isHelper)).toBe(true);
+
+      fs.writeFileSync(
+        path.join(late, 'codegraph.json'),
+        JSON.stringify({ deprioritize: ['optional-skills/'] })
+      );
+      const after = cg.searchNodes(QUERY, { limit: 20 });
+      const firstHelper = after.findIndex(isHelper);
+      const firstProduct = after.findIndex((r) => r.node.filePath.includes('apps/desktop'));
+      expect(firstProduct).toBeGreaterThanOrEqual(0);
+      expect(firstHelper === -1 || firstProduct < firstHelper).toBe(true);
+    } finally {
+      cg.destroy();
+      fs.rmSync(late, { recursive: true, force: true });
+    }
+  }, 180_000);
+});
+
+describe('scorePathRelevance — the two deliberate asymmetries (#982)', () => {
+  it('docks a path that is both test-like and de-prioritized only once', () => {
+    const both = 'example/a/foo.ts';
+    const asTestOnly = scorePathRelevance(both, 'foo');
+    const asBoth = scorePathRelevance(both, 'foo', undefined, true);
+    expect(asBoth).toBe(asTestOnly);
+  });
+
+  it('does not waive the user penalty for a test-y query, unlike the built-ins', () => {
+    // The built-in classification is inferred, so a test-y query waives it. A
+    // `deprioritize` pattern is a standing statement by the project, so it
+    // stands. Asserted so the difference is a decision, not an accident.
+    const builtIn = scorePathRelevance('example/a/foo.ts', 'foo test');
+    const userDeclared = scorePathRelevance('optional-skills/a/foo.ts', 'foo test', undefined, true);
+    expect(userDeclared).toBe(builtIn - 15);
+  });
+});
+
+describe('the name-bonus damping constant is derived, not picked (#982)', () => {
+  it('keeps a damped exact match above the prefix arm, so it cannot lose to one', () => {
+    // A de-prioritized node keeps `80 * SCALE` of the whole-query exact bonus
+    // and also takes the -15 path penalty. The prefix arm tops out below 40, so
+    // `80 * SCALE - 15 > 40` is what guarantees the exact match still wins —
+    // "discount, don't erase" stated as arithmetic instead of taste.
+    expect(nameMatchBonus('child', 'child')).toBe(80);
+    expect(nameMatchBonus('children', 'child')).toBeLessThan(40);
+    expect(80 * DEPRIORITIZED_NAME_BONUS_SCALE - 15).toBeGreaterThan(40);
+  });
+
+  it('would fail at the originally proposed 0.25, which is why it moved', () => {
+    // Measured on a 62k-node django index with `deprioritize: ["tests/"]`: at
+    // 0.25 the exact-name queries `child`, `parent` and `method` lost rank 1 to
+    // the prefix matches `children`, `all_parents` and `method_decorator`.
+    // Asserted so nobody lowers the constant back without meeting the bound.
+    expect(80 * 0.25 - 15).toBeLessThan(40);
+  });
+});

src/context/index.ts

@@ -188,6 +188,7 @@ export { LOW_CONFIDENCE_MARKER } from './markers';
 export class ContextBuilder {
   private projectRoot: string;
   private queries: QueryBuilder;
+
   private traverser: GraphTraverser;
 
   constructor(
@@ -200,6 +201,21 @@ export class ContextBuilder {
     this.traverser = traverser;
   }
 
+  /**
+   * Whether the project's `codegraph.json` `deprioritize` patterns cover this
+   * path (#982). Explore ranks through its own path scorer as well as through
+   * `searchNodes`, so the lever has to be applied here too or the setting would
+   * only half-work — and explore is the surface #982 actually reports on.
+   *
+   * Only the -15 relevance penalty is shared. Explore's hard `continue` filters
+   * and its non-production budget cap are deliberately NOT joined: those REMOVE
+   * content, and `deprioritize` is a ranking lever by definition — `exclude` is
+   * the lever for taking things out of reach.
+   */
+  private isDeprioritized(filePath: string): boolean {
+    return this.queries.getDeprioritizedPathMatcher()?.(filePath) ?? false;
+  }
+
   /**
    * Build context for a task
    *
@@ -837,7 +853,12 @@ export class ContextBuilder {
           if (searchIdSet.has(r.node.id)) continue;
           if (isTestFile(r.node.filePath) && !isTestQuery) continue;
 
-          const pathScore = scorePathRelevance(r.node.filePath, query);
+          const pathScore = scorePathRelevance(
+            r.node.filePath,
+            query,
+            undefined,
+            this.isDeprioritized(r.node.filePath),
+          );
           const brevityBonus = Math.max(0, 6 - (name.length - titleCased.length) / 4);
           termCandidates.push({ node: r.node, score: 8 + brevityBonus + pathScore });
         }
@@ -924,7 +945,12 @@ export class ContextBuilder {
         const compoundResults: SearchResult[] = [];
         for (const [, entry] of compoundTermMap) {
           if (entry.terms.size >= 2) {
-            const pathScore = scorePathRelevance(entry.node.filePath, query);
+            const pathScore = scorePathRelevance(
+              entry.node.filePath,
+              query,
+              undefined,
+              this.isDeprioritized(entry.node.filePath),
+            );
             const brevityBonus = Math.max(0, 6 - entry.node.name.length / 8);
             compoundResults.push({
               node: entry.node,

src/db/queries.ts

@@ -55,6 +55,23 @@ function isLowValueFile(filePath: string, generated?: ReadonlySet<string>): bool
 
 const SQLITE_PARAM_CHUNK_SIZE = 500;
 
+/**
+ * How much of the exact-name bonus a `deprioritize`d path keeps (#982). Damped
+ * rather than zeroed: a query that genuinely targets that tree must still rank
+ * it, the same "discount, don't erase" rule the path penalty follows.
+ *
+ * Derived rather than picked. `nameMatchBonus`'s prefix arm tops out below
+ * `10 + 30 = 40`, and a de-prioritized node also takes the -15 path penalty, so
+ * `80 * SCALE - 15 > 40` is what stops a damped WHOLE-QUERY exact match from
+ * losing to a mere prefix match. 0.75 clears it (45). Measured on a 62k-node
+ * django index: at 0.25 that invariant breaks in practice — `child`, `parent`
+ * and `method` lose rank 1 to `children`, `all_parents` and `method_decorator`
+ * — while crowd-out removal is almost flat between 0.75 and 0.5 (39 vs 40 of 88
+ * peripheral top-10 slots cleared), so a deeper discount buys little and costs
+ * the invariant. Pinned by a test.
+ */
+export const DEPRIORITIZED_NAME_BONUS_SCALE = 0.75;
+
 /**
  * Database row types (snake_case from SQLite)
  */
@@ -204,6 +221,7 @@ export class QueryBuilder {
   // whole project, not a symbol, so it carries no discriminative signal (#720).
   // Set once by the CodeGraph instance; empty by default (no down-weighting).
   private projectNameTokens: Set<string> = new Set();
+  private isDeprioritizedPath: ((filePath: string) => boolean) | undefined;
 
   // Node cache for frequently accessed nodes (LRU-style, max 1000 entries)
   private nodeCache: Map<string, Node> = new Map();
@@ -328,6 +346,21 @@ export class QueryBuilder {
     return this.projectNameTokens;
   }
 
+  /**
+   * Set the predicate that marks a path as de-prioritized by the project's
+   * `codegraph.json` `deprioritize` patterns (#982). Ranking-only: those paths
+   * stay indexed and findable, they just stop outranking first-party code.
+   * Called once when the project opens; undefined disables the lever.
+   */
+  setDeprioritizedPathMatcher(matcher: ((filePath: string) => boolean) | undefined): void {
+    this.isDeprioritizedPath = matcher;
+  }
+
+  /** The `deprioritize` predicate (#982), so other rankers apply the same lever. */
+  getDeprioritizedPathMatcher(): ((filePath: string) => boolean) | undefined {
+    return this.isDeprioritizedPath;
+  }
+
   // ===========================================================================
   // Node Operations
   // ===========================================================================
@@ -1295,13 +1328,24 @@ export class QueryBuilder {
     // Apply multi-signal scoring
     if (results.length > 0 && (text || query)) {
       const scoringQuery = text || query;
-      results = results.map(r => ({
-        ...r,
-        score: r.score
-          + kindBonus(r.node.kind)
-          + scorePathRelevance(r.node.filePath, scoringQuery, this.projectNameTokens)
-          + nameMatchBonus(r.node.name, scoringQuery),
-      }));
+      results = results.map(r => {
+        // A path the project de-prioritized is saying its symbol NAMES are not
+        // the answer, so the exact-name bonus has to be damped too. The -15 path
+        // penalty alone cannot do it: the bonus is additive and larger (measured
+        // on #982's repro, a `usage()` helper sat at 74.8 vs 51.2 for the top
+        // product symbol — -15 lands at 59.8, still ahead). Damped, not zeroed,
+        // so the tree stays findable when it genuinely is what you asked for.
+        // Evaluated once and reused: the predicate stats the config file.
+        const deprioritized = this.isDeprioritizedPath?.(r.node.filePath) ?? false;
+        const nameBonus = nameMatchBonus(r.node.name, scoringQuery);
+        return {
+          ...r,
+          score: r.score
+            + kindBonus(r.node.kind)
+            + scorePathRelevance(r.node.filePath, scoringQuery, this.projectNameTokens, deprioritized)
+            + (deprioritized ? Math.round(nameBonus * DEPRIORITIZED_NAME_BONUS_SCALE) : nameBonus),
+        };
+      });
       results.sort((a, b) => b.score - a.score);
       // Trim to requested limit after rescoring
       if (results.length > limit) {

src/index.ts

@@ -53,6 +53,8 @@ import { FileWatcher, WatchOptions, PendingFile, LockUnavailableError } from './
 import { EXTRACTION_VERSION } from './extraction/extraction-version';
 import { getCodeGraphDir } from './directory';
 import { deriveProjectNameTokens } from './search/query-utils';
+import ignore from 'ignore';
+import { loadDeprioritizePatterns } from './project-config';
 import { CodeGraphPackageVersion } from './mcp/version';
 import { extractSegmentSearchWords, segmentLookupVariants, splitIdentifierSegments } from './search/identifier-segments';
 import { createYielder } from './resolution/cooperative-yield';
@@ -186,6 +188,39 @@ export class CodeGraph {
     } catch {
       // Best-effort: ranking still works without it.
     }
+    // Down-weight the peripheral trees the project named in `codegraph.json`
+    // `deprioritize` — indexed and findable, but never outranking real code
+    // (#982). Ranking-only, so a bad pattern costs relevance, never recall.
+    //
+    // Read LAZILY, not once here: `wireLayers` runs from the constructor and
+    // from `reopenIfReplaced`, so a matcher built here would freeze at whatever
+    // the config said when the project opened. The MCP server caches one
+    // CodeGraph per root for its whole lifetime, so editing `codegraph.json`
+    // would appear to do nothing until the process restarted — `exclude` and
+    // `include` do not behave that way. `loadDeprioritizePatterns` is
+    // mtime-cached, so this costs one `stat`; the compiled matcher is memoized
+    // on the pattern array's identity, which the cache keeps stable.
+    let cachedPatterns: string[] | undefined;
+    let cachedMatcher: ReturnType<typeof ignore> | undefined;
+    this.queries.setDeprioritizedPathMatcher((filePath: string): boolean => {
+      try {
+        const patterns = loadDeprioritizePatterns(this.projectRoot);
+        if (patterns.length === 0) return false;
+        if (patterns !== cachedPatterns) {
+          cachedPatterns = patterns;
+          cachedMatcher = ignore().add(patterns);
+        }
+        const rel = path.isAbsolute(filePath)
+          ? path.relative(this.projectRoot, filePath)
+          : filePath;
+        if (!rel || rel.startsWith('..')) return false;
+        return cachedMatcher!.ignores(rel.split(path.sep).join('/'));
+      } catch {
+        // Ranking must never take the search down with it.
+        return false;
+      }
+    });
+
     this.orchestrator = new ExtractionOrchestrator(this.projectRoot, this.queries);
     this.resolver = createResolver(this.projectRoot, this.queries);
     this.graphManager = new GraphQueryManager(this.queries);

src/project-config.ts

@@ -67,6 +67,21 @@ export interface ProjectConfig {
    * wins. Absent/empty (the default) forces nothing in.
    */
   include?: string[];
+  /**
+   * Gitignore-style patterns for paths that should still be INDEXED and
+   * findable, but must not outrank first-party code in search ranking (#982).
+   *
+   * The ranking counterpart to `exclude`: `exclude` is a recall lever (the
+   * content leaves the index entirely), this is a relevance lever (the content
+   * stays, it just stops winning). It generalizes the built-in
+   * example/sample/fixture/benchmark de-prioritization to trees only the
+   * project knows about — an `optional-skills/` or `scripts/` directory whose
+   * helpers share generic symbol names with real code. Matched against
+   * project-root-relative paths, so `"optional-skills/"`, a recursive glob, or
+   * `"tools/gen"` all work. Absent/empty (the default) de-prioritizes nothing
+   * beyond the built-ins.
+   */
+  deprioritize?: string[];
 }
 
 /** Parsed, validated view of a project's `codegraph.json`. */
@@ -74,6 +89,7 @@ interface ParsedConfig {
   extensions: Record<string, Language>;
   includeIgnored: string[];
   exclude: string[];
+  deprioritize: string[];
   include: string[];
 }
 
@@ -97,6 +113,7 @@ const EMPTY_CONFIG: ParsedConfig = Object.freeze({
   includeIgnored: Object.freeze([]) as unknown as string[],
   exclude: Object.freeze([]) as unknown as string[],
   include: Object.freeze([]) as unknown as string[],
+  deprioritize: Object.freeze([]) as unknown as string[],
 });
 
 /**
@@ -149,15 +166,17 @@ function parseConfig(file: string): ParsedConfig {
   const includeIgnored = extractIncludeIgnored(parsed, file);
   const exclude = extractExclude(parsed, file);
   const include = extractInclude(parsed, file);
+  const deprioritize = extractPatternList(parsed, file, 'deprioritize');
   if (
     extensions === EMPTY_EXTENSIONS &&
     includeIgnored.length === 0 &&
     exclude.length === 0 &&
-    include.length === 0
+    include.length === 0 &&
+    deprioritize.length === 0
   ) {
     return EMPTY_CONFIG;
   }
-  return { extensions, includeIgnored, exclude, include };
+  return { extensions, includeIgnored, exclude, include, deprioritize };
 }
 
 /**
@@ -210,6 +229,29 @@ function extractIncludeIgnored(parsed: object, file: string): string[] {
   return out;
 }
 
+/**
+ * Validate a gitignore-style pattern list under `key`. A non-array value or a
+ * non-string/blank entry warns-and-skips; never throws. Patterns are kept
+ * verbatim (trimmed) so they match exactly as a `.gitignore` line would.
+ */
+function extractPatternList(parsed: object, file: string, key: 'deprioritize'): string[] {
+  const raw = (parsed as ProjectConfig)[key];
+  if (raw === undefined) return [];
+  if (!Array.isArray(raw)) {
+    logWarn(`Ignoring "${key}" in ${PROJECT_CONFIG_FILENAME}: must be an array of gitignore-style patterns`, { file });
+    return [];
+  }
+  const out: string[] = [];
+  for (const entry of raw) {
+    if (typeof entry !== 'string' || !entry.trim()) {
+      logWarn(`Ignoring a "${key}" entry in ${PROJECT_CONFIG_FILENAME}: every pattern must be a non-empty string`, { file });
+      continue;
+    }
+    out.push(entry.trim());
+  }
+  return out;
+}
+
 /**
  * Validate the `exclude` patterns: an array of non-empty gitignore-style
  * strings naming paths to keep out of the index even when git-tracked (#999). A
@@ -325,6 +367,17 @@ export function loadExcludePatterns(rootDir: string): string[] {
   return loadParsedConfig(rootDir).exclude;
 }
 
+/**
+ * Load the validated `deprioritize` patterns for a project, mtime-cached.
+ *
+ * These name indexed paths that must not outrank first-party code (#982) — the
+ * ranking counterpart to `exclude`. An empty result — the zero-config default —
+ * de-prioritizes nothing beyond the built-in example/fixture/benchmark dirs.
+ */
+export function loadDeprioritizePatterns(rootDir: string): string[] {
+  return loadParsedConfig(rootDir).deprioritize;
+}
+
 /**
  * Load the validated `include` patterns for a project, mtime-cached.
  *

src/search/query-utils.ts

@@ -222,6 +222,7 @@ export function scorePathRelevance(
   filePath: string,
   query: string,
   projectNameTokens?: Set<string>,
+  isDeprioritized?: boolean,
 ): number {
   const pathLower = filePath.toLowerCase();
   const fileName = path.basename(filePath).toLowerCase();
@@ -264,10 +265,19 @@ export function scorePathRelevance(
     else if (subtokens.some((t) => pathLower.includes(t))) score += 3;
   }
 
-  // Deprioritize test files unless the query is explicitly about tests
+  // Deprioritize test files unless the query is explicitly about tests, and
+  // apply the same -15 to a path the project declared peripheral (#982).
+  //
+  // Two deliberate asymmetries, both pinned by tests:
+  //  - the built-in test/fixture penalty is waived for a test-y query, because
+  //    the tool inferred that classification; a `deprioritize` pattern is a
+  //    standing statement by the project, so it is NOT waived. The name-bonus
+  //    damping at the call site is what keeps such a tree findable.
+  //  - a path that is both is docked ONCE, not twice.
   const queryLower = query.toLowerCase();
   const isTestQuery = queryLower.includes('test') || queryLower.includes('spec');
-  if (!isTestQuery && isTestFile(filePath)) {
+  const offTarget = (!isTestQuery && isTestFile(filePath)) || isDeprioritized === true;
+  if (offTarget) {
     score -= 15;
   }