Root directory based activation

Author: gbro3n

README.md

@@ -308,7 +308,7 @@ For a sample knowledge base, clone https://github.com/appsoftwareltd/as-notes-de
 
 ### Initialise a workspace
 
-AS Notes activates when it finds a `.asnotes/` directory in your workspace root (similar to `.git/` or `.obsidian/`). Without it, the extension runs in **passive mode** — commands show a friendly notification prompting you to initialise, and the status bar invites you to set up.
+AS Notes activates when it finds a `.asnotes/` directory in your workspace root or configured `rootDirectory` subdirectory (similar to `.git/` or `.obsidian/`). Without it, the extension runs in **passive mode** -- commands show a friendly notification prompting you to initialise, and the status bar invites you to set up.
 
 To initialise:
 
@@ -317,6 +317,21 @@ To initialise:
 
 This creates the `.asnotes/` directory, builds a SQLite index of all markdown files, and activates all features. The index file (`.asnotes/index.db`) is excluded from git by an auto-generated `.gitignore`.
 
+### Using AS Notes alongside source code
+
+AS Notes works well as a knowledge base inside a software project. You can keep notes, journals, and documentation in a subdirectory (e.g. `docs/` or `notes/`) while the rest of the repository contains source code. When a root directory is configured, all AS Notes features (wikilink highlighting, completions, hover tooltips, slash commands) are scoped to that directory. Markdown files outside it, such as a `README.md` at the workspace root, are completely unaffected.
+
+During initialisation, the **Initialise Workspace** command will ask you to choose a location:
+
+- **Workspace root** - the default, uses the entire workspace
+- **Choose a subdirectory** - opens a folder picker scoped to your workspace
+
+The chosen path is saved as the `as-notes.rootDirectory` workspace setting. When set, all AS Notes data lives inside that directory: `.asnotes/`, `.asnotesignore`, journals, templates, notes, kanban boards, and the index. Scanning, file watching, and indexing are scoped to this directory so files outside it are unaffected.
+
+If `as-notes.rootDirectory` is already configured before you run **Initialise Workspace**, the command uses the configured path directly.
+
+> **Warning:** If you change `rootDirectory` after initialisation, you must manually move the notes directory (including `.asnotes/`) to the new location and reload the window. The extension will show a warning when the setting changes.
+
 ### Rebuild the index
 
 If the index becomes stale or corrupted, run **AS Notes: Rebuild Index** from the Command Palette. This drops and recreates the entire index with a progress indicator.
@@ -328,11 +343,11 @@ If the extension is in a bad state (e.g. persistent WASM errors after a crash),
 - Removes the `.asnotes/` directory (index database, logs, git hook config)
 - Releases all in-memory state and switches to passive mode
 
-`.asnotesignore` at the workspace root is intentionally preserved. Run **AS Notes: Initialise Workspace** afterwards to start fresh.
+`.asnotesignore` at the AS Notes root is intentionally preserved. Run **AS Notes: Initialise Workspace** afterwards to start fresh.
 
 ### Excluding files from the index
 
-When AS Notes initialises a workspace it creates a `.asnotesignore` file at the workspace root. This file uses [`.gitignore` pattern syntax](https://git-scm.com/docs/gitignore) and controls which files and directories are excluded from the AS Notes index.
+When AS Notes initialises a workspace it creates a `.asnotesignore` file at the AS Notes root directory. This file uses [`.gitignore` pattern syntax](https://git-scm.com/docs/gitignore) and controls which files and directories are excluded from the AS Notes index.
 
 **Default contents:**
 
@@ -345,7 +360,7 @@ logseq/
 .trash/
 ```
 
-Patterns without a leading `/` match at any depth - `logseq/` excludes `logseq/pages/foo.md` and `vaults/work/logseq/pages/foo.md` equally. Prefix with `/` to anchor a pattern to the workspace root only (e.g. `/logseq/`).
+Patterns without a leading `/` match at any depth - `logseq/` excludes `logseq/pages/foo.md` and `vaults/work/logseq/pages/foo.md` equally. Prefix with `/` to anchor a pattern to the AS Notes root only (e.g. `/logseq/`).
 
 Edit `.asnotesignore` at any time. AS Notes watches the file and automatically re-scans the index when it changes - newly ignored files are removed from the index and un-ignored files are added.
 
@@ -569,7 +584,7 @@ The **AS Notes Kanban** sidebar and editor panel let you manage work visually wi
 
 #### Boards
 
-A workspace can contain any number of named boards, stored as plain files in a `kanban/` directory at the workspace root. Each board has its own lanes and set of cards.
+A workspace can contain any number of named boards, stored as plain files in a `kanban/` directory at the AS Notes root. Each board has its own lanes and set of cards.
 
 - **Create a board** — run **AS Notes: Create Kanban Board** from the Command Palette and enter a name. The first board is selected automatically on activation.
 - **Switch board** — type in the board-switcher field in the sidebar to filter and select from existing boards. The editor panel opens automatically.
@@ -664,11 +679,12 @@ Front-matter holds the structured fields; the Markdown body is the card descript
 
 | Setting | Default | Description |
 |---|---|---|
+| `as-notes.rootDirectory` | *(empty)* | Relative path from the workspace root to the AS Notes root directory (e.g. `docs` or `notes`). Leave empty to use the workspace root. All AS Notes data (`.asnotes/`, journals, templates, notes, kanban, `.asnotesignore`) lives within this directory. See [Using AS Notes in a subdirectory](#using-as-notes-in-a-subdirectory) below. |
 | `as-notes.periodicScanInterval` | `300` | Seconds between automatic background scans for file changes. Set to `0` to disable. Minimum: `30`. |
-| `as-notes.journalFolder` | `journals` | Folder for daily journal files, relative to workspace root. |
-| `as-notes.notesFolder` | `notes` | Folder for new notes, relative to workspace root. Used when creating pages via wikilink navigation and the Create Note / Create Encrypted Note commands. |
+| `as-notes.journalFolder` | `journals` | Folder for daily journal files, relative to the AS Notes root directory. |
+| `as-notes.notesFolder` | `notes` | Folder for new notes, relative to the AS Notes root directory. Used when creating pages via wikilink navigation and the Create Note / Create Encrypted Note commands. |
 | `as-notes.createNotesInCurrentDirectory` | `false` | When enabled, new notes created via wikilink navigation are placed in the current editing file's directory instead of the notes folder. Ignored when the source file is in the journal folder. |
-| `as-notes.templateFolder` | `templates` | Folder for note templates, relative to workspace root. Templates are markdown files inserted via the `/Template` slash command. |
+| `as-notes.templateFolder` | `templates` | Folder for note templates, relative to the AS Notes root directory. Templates are markdown files inserted via the `/Template` slash command. |
 | `as-notes.licenceKey` | *(empty)* | AS Notes Pro licence key (format: `ASNO-XXXX-XXXX-XXXX-XXXX`). Enter via **AS Notes: Enter Licence Key** in the Command Palette or directly in Settings. Scope: machine (not synced). |
 | `as-notes.enableLogging` | `false` | Enable diagnostic logging to `.asnotes/logs/`. Rolling 10 MB files, max 5. Requires reload after changing. Also activated by setting the `AS_NOTES_DEBUG=1` environment variable. |
 
@@ -709,7 +725,7 @@ AS Notes directories can be managed via sync, though Git is recommended as it do
 The backlinks panel shows this message when the current file is not in the AS Notes index. Common causes:
 
 - **VS Code `files.exclude` / `search.exclude` settings** - AS Notes uses `vscode.workspace.findFiles()` to discover markdown files, which respects these VS Code settings. Files in excluded folders (e.g. `logseq/version-files/`) are silently omitted from the scan and will never be indexed. Check **Settings → Files: Exclude** and **Settings → Search: Exclude** if a file you expect to be indexed is missing.
-- **`.asnotesignore` patterns** - Files matching patterns in `.asnotesignore` at the workspace root are excluded from the index. See [Excluding files from the index](#excluding-files-from-the-index) above.
+- **`.asnotesignore` patterns** - Files matching patterns in `.asnotesignore` at the AS Notes root are excluded from the index. See [Excluding files from the index](#excluding-files-from-the-index) above.
 - **File not yet saved** - New unsaved files are not indexed until they are saved to disk for the first time.
 
 To resolve, check your workspace settings and `.asnotesignore` file. If the file should be indexed, ensure it is not matched by any exclusion pattern, then run **AS Notes: Rebuild Index** from the Command Palette.

TECHNICAL.md

@@ -426,7 +426,7 @@ This allows users to "uninitialise" a workspace by simply deleting the `.asnotes
 
 ## Activation model
 
-The extension uses a `.asnotes/` directory in the workspace root as a project marker (analogous to `.git/` or `.obsidian/`). Its presence determines the operating mode.
+The extension uses a `.asnotes/` directory in the workspace root (or a configured `rootDirectory` subdirectory) as a project marker (analogous to `.git/` or `.obsidian/`). Its presence determines the operating mode.
 
 ### Passive mode
 
@@ -558,12 +558,74 @@ The **AS Notes: Clean Workspace** command (`as-notes.cleanWorkspace`) performs a
 3. `fs.rmSync(.asnotes/, { recursive: true, force: true })` — deletes the entire `.asnotes/` directory tree (index database, logs, git hook config).
 4. Shows an informational message directing the user to run **Initialise Workspace** to start fresh.
 
-`.asnotesignore` at the workspace root is intentionally preserved — it is a user-editable, version-controlled configuration file.
+`.asnotesignore` at the AS Notes root is intentionally preserved -- it is a user-editable, version-controlled configuration file.
 
 If the `.asnotes/` directory does not exist, the command shows an informational message and returns early. If the directory deletion fails (e.g. file lock on Windows), an error message is displayed.
 
 ---
 
+## Root directory (subdirectory mode)
+
+### Setting: `as-notes.rootDirectory`
+
+The `as-notes.rootDirectory` setting allows AS Notes to operate in a subdirectory of the workspace rather than the workspace root. When empty (default), behaviour is identical to previous versions (full backward compatibility). When set to a relative path like `docs` or `notes/wiki`, all AS Notes data lives under that directory.
+
+The setting is declared with `"scope": "resource"` in the extension manifest. This means VS Code resolves it per workspace folder rather than globally. The value is inherently workspace-specific (a relative path within that workspace), so it should always be set in Workspace settings, never in User settings. The `resource` scope ensures the setting appears in the correct section of the Settings UI and is stored in `.vscode/settings.json`.
+
+### NotesRootService
+
+`NotesRootService.ts` is a pure-logic module (no VS Code imports) that centralises all path computation related to the notes root:
+
+| Export | Purpose |
+|---|---|
+| `normaliseRootDirectory(dir)` | Strips leading/trailing slashes, normalises separators |
+| `computeNotesRoot(workspaceRoot, rootDirectory)` | Returns the absolute notes root path |
+| `computeNotesRootPaths(workspaceRoot, rootDirectory)` | Returns a `NotesRootPaths` object with all well-known paths (`root`, `rootUri`, `asnotesDir`, `databasePath`, `logDir`, `ignoreFilePath`) |
+| `toNotesRelativePath(notesRoot, absolutePath)` | Computes a notes-root-relative path (replacing `vscode.workspace.asRelativePath()` for index lookups) |
+| `isInsideNotesRoot(notesRoot, absolutePath)` | Checks whether a path is inside the notes root |
+
+### Architecture pattern
+
+- **Single source of truth:** Module-level `notesRootPaths: NotesRootPaths` and `notesRootUri: vscode.Uri` in `extension.ts`, computed once during activation from the workspace root and `rootDirectory` setting.
+- **Service injection:** Services receive the notes root via constructor parameter (`WikilinkFileService`, `WikilinkRenameTracker`, `BacklinkPanelProvider`) or setter method (`SearchPanelProvider.setNotesRootUri()`, `TaskPanelProvider.setNotesRootUri()`).
+- **Scoped scanning:** `IndexScanner` uses `vscode.RelativePattern(notesRoot, '**/*.{md,markdown}')` to limit `findFiles()` to the notes root. The same pattern scopes encrypted file scanning.
+- **Notes-root-relative paths:** All paths stored in the index (the `pages.path` column) are relative to the notes root, not the workspace root. The `toNotesRelativePath()` function replaces `workspace.asRelativePath()` throughout event handlers, rename tracking, and backlink resolution.
+- **Fallback safety:** Where `notesRootPaths` may be null (e.g. before activation completes or during teardown), code falls back to `vscode.workspace.asRelativePath()` or `workspaceFolders[0]`.
+
+### Initialisation flow
+
+When **Initialise Workspace** runs and `rootDirectory` is not yet configured:
+
+1. A `QuickPick` offers "Workspace root" or "Choose subdirectory..."
+2. If "Choose subdirectory..." is selected, `showOpenDialog` opens a folder picker scoped to the workspace
+3. The chosen relative path is saved to `as-notes.rootDirectory` as a workspace-scoped setting
+4. `.asnotes/`, `.asnotesignore`, and configured folders are created at the chosen root
+5. The extension enters full mode with scanning scoped to the chosen root
+
+### Configuration change handling
+
+When `as-notes.rootDirectory` changes after activation, the extension shows a warning: "AS Notes root directory changed. Reload the window for changes to take effect.", with a "Reload Window" action. The extension does not auto-migrate data.
+
+### Feature scoping to the notes root
+
+When `rootDirectory` is configured, AS Notes features are completely invisible for markdown files outside the notes root. A `README.md` at the workspace root will have no wikilink highlighting, no hover tooltips, no completions, and no slash commands.
+
+**Language providers:** The `DocumentSelector` used for all `register*Provider` calls includes a `RelativePattern` when `rootDirectory` is set:
+
+```typescript
+const markdownSelector = nrUri
+    ? { language: 'markdown', pattern: new RelativePattern(nrUri, '**') }
+    : { language: 'markdown' };
+```
+
+VS Code only invokes the provider when both the language and the pattern match. When `rootDirectory` is empty, no pattern is applied (all markdown files match, same as before).
+
+**WikilinkDecorationManager:** Receives `notesRootFsPath` and guards `rebuildCacheAndDecorate()` and `applyDecorations()` with `isInsideNotesRoot()`. Files outside the root get stale decorations cleared.
+
+**Event handlers:** All seven event handlers in `extension.ts` (`onDidSaveTextDocument`, `onDidChangeTextDocument` x2, `onDidCreateFiles`, `onDidDeleteFiles`, `onDidRenameFiles`, `onDidChangeActiveTextEditor`) include an early `isInsideNotesRoot()` bail-out. When `notesRootPaths` is null (backward compat), the guard is skipped.
+
+---
+
 ## Aliases and front matter
 
 ### FrontMatterService

vs-code-extension/package.json

@@ -222,6 +222,12 @@
         "configuration": {
             "title": "AS Notes",
             "properties": {
+                "as-notes.rootDirectory": {
+                    "type": "string",
+                    "default": "",
+                    "scope": "resource",
+                    "description": "Subdirectory for AS Notes within the workspace (e.g. 'docs' or 'notes'). When empty, the workspace root is used. All AS Notes data (.asnotes, journals, templates, etc.) lives within this directory. Configure this per workspace, not globally. Warning: if you change this after initialisation, you must manually move your notes directory to the new location."
+                },
                 "as-notes.periodicScanInterval": {
                     "type": "number",
                     "default": 300,
@@ -231,7 +237,7 @@
                 "as-notes.journalFolder": {
                     "type": "string",
                     "default": "journals",
-                    "description": "Folder for daily journal files, relative to workspace root."
+                    "description": "Folder for daily journal files, relative to the AS Notes root directory."
                 },
                 "as-notes.licenceKey": {
                     "type": "string",
@@ -242,7 +248,7 @@
                 "as-notes.assetPath": {
                     "type": "string",
                     "default": "assets/images",
-                    "description": "Workspace-relative folder where dropped or pasted files are saved by VS Code's built-in markdown editor. AS Notes configures the built-in markdown.copyFiles.destination setting to use this path."
+                    "description": "Folder where dropped or pasted files are saved by VS Code's built-in markdown editor, relative to the AS Notes root directory. AS Notes configures the built-in markdown.copyFiles.destination setting to use this path."
                 },
                 "as-notes.enableLogging": {
                     "type": "boolean",
@@ -279,12 +285,12 @@
                 "as-notes.templateFolder": {
                     "type": "string",
                     "default": "templates",
-                    "description": "Folder for note templates, relative to workspace root. Templates are markdown files that can be inserted via the /Template slash command."
+                    "description": "Folder for note templates, relative to the AS Notes root directory. Templates are markdown files that can be inserted via the /Template slash command."
                 },
                 "as-notes.notesFolder": {
                     "type": "string",
                     "default": "notes",
-                    "description": "Folder for new notes, relative to workspace root. Used when creating pages via wikilink navigation and the Create Note / Create Encrypted Note commands."
+                    "description": "Folder for new notes, relative to the AS Notes root directory. Used when creating pages via wikilink navigation and the Create Note / Create Encrypted Note commands."
                 },
                 "as-notes.createNotesInCurrentDirectory": {
                     "type": "boolean",

vs-code-extension/src/BacklinkPanelProvider.ts

@@ -2,6 +2,7 @@ import * as vscode from 'vscode';
 import { IndexService, type BacklinkChainGroup, type BacklinkChainInstance, type PageRow } from './IndexService.js';
 import type { LogService } from './LogService.js';
 import * as path from 'path';
+import { toNotesRelativePath } from './NotesRootService.js';
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -214,7 +215,7 @@ export class BacklinkPanelProvider implements vscode.Disposable {
     private renderBacklinksForUri(uri: vscode.Uri): void {
         if (!this.panel || !this.indexService.isOpen) { return; }
 
-        const relativePath = vscode.workspace.asRelativePath(uri, false);
+        const relativePath = toNotesRelativePath(this.workspaceRoot.fsPath, uri.fsPath);
         this.logger?.info('BacklinkPanel', `renderBacklinksForUri: looking up path="${relativePath}" from uri="${uri.toString()}"`);
         const page = this.indexService.getPageByPath(relativePath);