hammoc 1.4.0 → 1.5.0

package/packages/server/dist/utils/snippetPaths.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Story 29.2: Snippet path resolver.
+ *
+ * The snippet system has three scopes that map to different on-disk roots:
+ *
+ *   - project   → `<projectRoot>/.hammoc/snippets/`
+ *   - user      → `~/.hammoc/snippets/`
+ *   - bundled   → server-bundled snippets (read-only, located alongside the
+ *                 server build at `<serverDist>/snippets/`)
+ *
+ * `resolveSnippetPath` is the only path-shaping entry point used by
+ * `snippetService` — it accepts `{ scope, projectSlug?, name }` and never lets
+ * a caller-supplied relative path through. NAME_RE rejects anything outside
+ * `[A-Za-z0-9._-]+` so directory traversal (`..`, `/`, `\`, `\0`, drive
+ * letters, UNC prefixes) is impossible by construction.
+ *
+ * On-disk filename normalization: writes always land at `<root>/<name>.md`
+ * regardless of input form. Reads accept both `<name>.md` and the legacy
+ * extension-less `<name>` (snippetResolver supports both for back-compat) so
+ * existing bundled and user files continue to load.
+ */
+/** Snippet name regex — same shape as snippetResolver's NAME_RE. */
+export declare const SNIPPET_NAME_RE: RegExp;
+/** Return the absolute path of `~/.hammoc/snippets/`. */
+export declare function getUserSnippetsDir(): string;
+/** Return the absolute path of the server-bundled snippets directory. */
+export declare function getBundledSnippetsDir(): string;
+/** Return the absolute path of `<projectRoot>/.hammoc/snippets/`. */
+export declare function getProjectSnippetsDir(projectSlug: string): Promise<string>;
+export interface ResolvedSnippetPath {
+    /** Root directory (the snippets dir itself, not the project root). */
+    resolvedRoot: string;
+    /** `<resolvedRoot>/<name>.md`. */
+    absolutePath: string;
+    /** Same path but without `.md` — legacy format used for back-compat reads. */
+    legacyAbsolutePath: string;
+    /** True when this path is read-only (bundled). */
+    readOnly: boolean;
+}
+export type SnippetScope = 'project' | 'user' | 'bundled';
+export interface SnippetPathRef {
+    scope: SnippetScope;
+    /** Required when scope === 'project'. */
+    projectSlug?: string;
+    name: string;
+}
+/**
+ * Resolve a snippet path with NAME_RE validation and bundled read-only flagging.
+ * Throws an Error with `code: 'HARNESS_PATH_DENIED'` for invalid names.
+ */
+export declare function resolveSnippetPath(ref: SnippetPathRef): Promise<ResolvedSnippetPath>;
+/**
+ * Throws an HARNESS_PATH_DENIED Error when the name is invalid.
+ *
+ * Note: SNIPPET_NAME_RE allows `.` so single-dot names (`a.b`) pass through.
+ * That also means literal `..` would pass the regex — we reject it
+ * separately below, mirroring snippetResolver.resolveSnippet's defensive
+ * filter.
+ */
+export declare function validateSnippetName(name: string): void;
+//# sourceMappingURL=snippetPaths.d.ts.map

package/packages/server/dist/utils/snippetPaths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snippetPaths.d.ts","sourceRoot":"","sources":["../../src/utils/snippetPaths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAaH,oEAAoE;AACpE,eAAO,MAAM,eAAe,QAAsB,CAAC;AAOnD,yDAAyD;AACzD,wBAAgB,kBAAkB,IAAI,MAAM,CAM3C;AAED,yEAAyE;AACzE,wBAAgB,qBAAqB,IAAI,MAAM,CAM9C;AAED,qEAAqE;AACrE,wBAAsB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAchF;AAED,MAAM,WAAW,mBAAmB;IAClC,sEAAsE;IACtE,YAAY,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,kBAAkB,EAAE,MAAM,CAAC;IAC3B,kDAAkD;IAClD,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;AAE1D,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,YAAY,CAAC;IACpB,yCAAyC;IACzC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA4B1F;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAatD"}

package/packages/server/dist/utils/snippetPaths.js

@@ -0,0 +1,123 @@
+/**
+ * Story 29.2: Snippet path resolver.
+ *
+ * The snippet system has three scopes that map to different on-disk roots:
+ *
+ *   - project   → `<projectRoot>/.hammoc/snippets/`
+ *   - user      → `~/.hammoc/snippets/`
+ *   - bundled   → server-bundled snippets (read-only, located alongside the
+ *                 server build at `<serverDist>/snippets/`)
+ *
+ * `resolveSnippetPath` is the only path-shaping entry point used by
+ * `snippetService` — it accepts `{ scope, projectSlug?, name }` and never lets
+ * a caller-supplied relative path through. NAME_RE rejects anything outside
+ * `[A-Za-z0-9._-]+` so directory traversal (`..`, `/`, `\`, `\0`, drive
+ * letters, UNC prefixes) is impossible by construction.
+ *
+ * On-disk filename normalization: writes always land at `<root>/<name>.md`
+ * regardless of input form. Reads accept both `<name>.md` and the legacy
+ * extension-less `<name>` (snippetResolver supports both for back-compat) so
+ * existing bundled and user files continue to load.
+ */
+import os from 'os';
+import path from 'path';
+import { fileURLToPath } from 'node:url';
+import { projectService } from '../services/projectService.js';
+/** Hammoc home root override for tests. Mirrors `HAMMOC_HARNESS_HOME_OVERRIDE`. */
+const HOME_OVERRIDE_ENV = 'HAMMOC_HOME_OVERRIDE';
+/** Bundled snippet directory override for tests (e.g. point at a tmp dir). */
+const BUNDLED_OVERRIDE_ENV = 'HAMMOC_BUNDLED_SNIPPETS_DIR';
+/** Snippet name regex — same shape as snippetResolver's NAME_RE. */
+export const SNIPPET_NAME_RE = /^[a-zA-Z0-9._-]+$/;
+const SNIPPETS_SUBDIR = '.hammoc/snippets';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_BUNDLED_DIR = path.resolve(__dirname, '..', 'snippets');
+/** Return the absolute path of `~/.hammoc/snippets/`. */
+export function getUserSnippetsDir() {
+    const override = process.env[HOME_OVERRIDE_ENV];
+    if (override && override.length > 0) {
+        return path.join(override, '.hammoc', 'snippets');
+    }
+    return path.join(os.homedir(), '.hammoc', 'snippets');
+}
+/** Return the absolute path of the server-bundled snippets directory. */
+export function getBundledSnippetsDir() {
+    const override = process.env[BUNDLED_OVERRIDE_ENV];
+    if (override && override.length > 0) {
+        return override;
+    }
+    return DEFAULT_BUNDLED_DIR;
+}
+/** Return the absolute path of `<projectRoot>/.hammoc/snippets/`. */
+export async function getProjectSnippetsDir(projectSlug) {
+    if (!projectSlug) {
+        throw makePathDeniedError('projectSlug is required for project scope');
+    }
+    if (projectSlug.includes('\0') ||
+        projectSlug.includes('..') ||
+        projectSlug.includes('/') ||
+        projectSlug.includes('\\')) {
+        throw makePathDeniedError('projectSlug must not contain path separators');
+    }
+    const projectRoot = await projectService.resolveOriginalPath(projectSlug);
+    return path.join(projectRoot, SNIPPETS_SUBDIR);
+}
+/**
+ * Resolve a snippet path with NAME_RE validation and bundled read-only flagging.
+ * Throws an Error with `code: 'HARNESS_PATH_DENIED'` for invalid names.
+ */
+export async function resolveSnippetPath(ref) {
+    validateSnippetName(ref.name);
+    let resolvedRoot;
+    let readOnly = false;
+    if (ref.scope === 'project') {
+        if (!ref.projectSlug) {
+            throw makePathDeniedError('projectSlug is required for project scope');
+        }
+        resolvedRoot = path.resolve(await getProjectSnippetsDir(ref.projectSlug));
+    }
+    else if (ref.scope === 'user') {
+        resolvedRoot = path.resolve(getUserSnippetsDir());
+    }
+    else {
+        resolvedRoot = path.resolve(getBundledSnippetsDir());
+        readOnly = true;
+    }
+    // Belt + suspenders: even though NAME_RE forbids separators, double-check
+    // the resolved file stays inside the root.
+    const absolutePath = path.resolve(resolvedRoot, `${ref.name}.md`);
+    if (absolutePath !== resolvedRoot &&
+        !absolutePath.startsWith(resolvedRoot + path.sep)) {
+        throw makePathDeniedError('snippet path escapes root');
+    }
+    const legacyAbsolutePath = path.resolve(resolvedRoot, ref.name);
+    return { resolvedRoot, absolutePath, legacyAbsolutePath, readOnly };
+}
+/**
+ * Throws an HARNESS_PATH_DENIED Error when the name is invalid.
+ *
+ * Note: SNIPPET_NAME_RE allows `.` so single-dot names (`a.b`) pass through.
+ * That also means literal `..` would pass the regex — we reject it
+ * separately below, mirroring snippetResolver.resolveSnippet's defensive
+ * filter.
+ */
+export function validateSnippetName(name) {
+    if (!name || typeof name !== 'string') {
+        throw makePathDeniedError('snippet name is required');
+    }
+    if (name.includes('\0')) {
+        throw makePathDeniedError('null byte in snippet name');
+    }
+    if (name === '..' || name === '.' || name.includes('/') || name.includes('\\')) {
+        throw makePathDeniedError(`path traversal denied: ${name}`);
+    }
+    if (!SNIPPET_NAME_RE.test(name)) {
+        throw makePathDeniedError(`invalid snippet name: ${name}`);
+    }
+}
+function makePathDeniedError(message) {
+    const err = new Error(message);
+    err.code = 'HARNESS_PATH_DENIED';
+    return err;
+}
+//# sourceMappingURL=snippetPaths.js.map

package/packages/server/dist/utils/snippetPaths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snippetPaths.js","sourceRoot":"","sources":["../../src/utils/snippetPaths.ts"],"names":[],"mappings":"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"}

package/packages/server/dist/utils/structuredEditor.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Story 28.0.5: YAML / JSONC round-trip editor.
+ *
+ * The goal is to mutate a single key inside a structured config file while
+ * preserving the author's comments, blank lines, key order, and quoting style.
+ *
+ * - YAML  → `yaml` (eemeli) `parseDocument` + `doc.setIn/deleteIn` + `doc.toString()`.
+ *           The Document AST keeps comment & blank-line metadata attached to
+ *           each node, and `toString()` re-emits them.
+ *   NOTE: `js-yaml@4` remains a coexisting dependency for session-meta parsing
+ *   elsewhere in the codebase, but has no comment-preservation path and must
+ *   not be used for harness edits.
+ *
+ * - JSONC → `jsonc-parser` `modify` + `applyEdits`. This is the same path VS
+ *           Code uses when it edits user `settings.json` — comments and
+ *           formatting are preserved.
+ *
+ * Both entry points throw `HARNESS_PARSE_ERROR` on unparseable input so the
+ * harness controller can surface the envelope and the client can fall back to
+ * raw editing.
+ */
+import { type HarnessStructuredPatchOp } from '@hammoc/shared';
+/**
+ * Apply structured patches to a YAML source string while preserving comments,
+ * blank lines, and key order.
+ */
+export declare function applyYamlPatch(source: string, ops: HarnessStructuredPatchOp[]): string;
+/**
+ * Apply structured patches to a JSONC source string while preserving comments
+ * and formatting. Inserts missing intermediate objects as needed (matches
+ * `jsonc-parser` `modify` default behavior).
+ */
+export declare function applyJsoncPatch(source: string, ops: HarnessStructuredPatchOp[]): string;
+//# sourceMappingURL=structuredEditor.d.ts.map

package/packages/server/dist/utils/structuredEditor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structuredEditor.d.ts","sourceRoot":"","sources":["../../src/utils/structuredEditor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAaH,OAAO,EAAkB,KAAK,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAQ/E;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,wBAAwB,EAAE,GAAG,MAAM,CAmCtF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,wBAAwB,EAAE,GAAG,MAAM,CAqCvF"}

package/packages/server/dist/utils/structuredEditor.js

@@ -0,0 +1,111 @@
+/**
+ * Story 28.0.5: YAML / JSONC round-trip editor.
+ *
+ * The goal is to mutate a single key inside a structured config file while
+ * preserving the author's comments, blank lines, key order, and quoting style.
+ *
+ * - YAML  → `yaml` (eemeli) `parseDocument` + `doc.setIn/deleteIn` + `doc.toString()`.
+ *           The Document AST keeps comment & blank-line metadata attached to
+ *           each node, and `toString()` re-emits them.
+ *   NOTE: `js-yaml@4` remains a coexisting dependency for session-meta parsing
+ *   elsewhere in the codebase, but has no comment-preservation path and must
+ *   not be used for harness edits.
+ *
+ * - JSONC → `jsonc-parser` `modify` + `applyEdits`. This is the same path VS
+ *           Code uses when it edits user `settings.json` — comments and
+ *           formatting are preserved.
+ *
+ * Both entry points throw `HARNESS_PARSE_ERROR` on unparseable input so the
+ * harness controller can surface the envelope and the client can fall back to
+ * raw editing.
+ */
+import { parseDocument } from 'yaml';
+import { modify, applyEdits, parse, parseTree, findNodeAtLocation, printParseErrorCode, } from 'jsonc-parser';
+import { HARNESS_ERRORS } from '@hammoc/shared';
+function parseError(format, cause) {
+    const err = new Error(`failed to parse ${format}: ${cause?.message ?? String(cause)}`);
+    err.code = HARNESS_ERRORS.HARNESS_PARSE_ERROR.code;
+    return err;
+}
+/**
+ * Apply structured patches to a YAML source string while preserving comments,
+ * blank lines, and key order.
+ */
+export function applyYamlPatch(source, ops) {
+    let doc;
+    try {
+        doc = parseDocument(source, { keepSourceTokens: true });
+        if (doc.errors.length > 0) {
+            throw doc.errors[0];
+        }
+    }
+    catch (cause) {
+        throw parseError('yaml', cause);
+    }
+    // A freshly-created empty document has `contents: null`; we need a map so
+    // setIn can plant new keys at the top level.
+    if (doc.contents == null) {
+        doc.contents = doc.createNode({});
+    }
+    for (const op of ops) {
+        if (!op.path || op.path.length === 0) {
+            throw parseError('yaml', new Error('patch op requires a non-empty path'));
+        }
+        if (op.value === undefined) {
+            // Idempotent delete: if any segment (including intermediates) is already
+            // absent, the target is effectively deleted — skip. `doc.deleteIn`
+            // itself only no-ops on a missing leaf; a missing intermediate throws.
+            if (!doc.hasIn(op.path))
+                continue;
+            doc.deleteIn(op.path);
+        }
+        else {
+            doc.setIn(op.path, op.value);
+        }
+    }
+    // toString() preserves original comments/blank lines/quote style for any
+    // node that was not explicitly replaced.
+    return doc.toString();
+}
+/**
+ * Apply structured patches to a JSONC source string while preserving comments
+ * and formatting. Inserts missing intermediate objects as needed (matches
+ * `jsonc-parser` `modify` default behavior).
+ */
+export function applyJsoncPatch(source, ops) {
+    // Validate the source up front — `modify` silently starts from `{}` on
+    // garbage input, which would quietly erase the user's file. Feed the
+    // official errors array to catch unterminated strings, missing values, etc.
+    if (source.trim().length > 0) {
+        const errors = [];
+        parse(source, errors, { allowTrailingComma: true, disallowComments: false });
+        if (errors.length > 0) {
+            const first = errors[0];
+            throw parseError('jsonc', new Error(`${printParseErrorCode(first.error)} at offset ${first.offset}`));
+        }
+    }
+    const formattingOptions = {
+        insertSpaces: true,
+        tabSize: 2,
+        eol: source.includes('\r\n') ? '\r\n' : '\n',
+    };
+    let current = source;
+    for (const op of ops) {
+        if (!op.path || op.path.length === 0) {
+            throw parseError('jsonc', new Error('patch op requires a non-empty path'));
+        }
+        // Idempotent delete: `modify(undefined)` throws "Can not delete…" when the
+        // target (or any intermediate) does not exist; treat that as a no-op so
+        // callers can apply delete patches without first probing state.
+        if (op.value === undefined) {
+            const tree = parseTree(current, [], { allowTrailingComma: true, disallowComments: false });
+            if (!tree || !findNodeAtLocation(tree, op.path))
+                continue;
+        }
+        // `modify` takes `undefined` to mean "remove", matching HarnessStructuredPatchOp.value semantics.
+        const edits = modify(current, op.path, op.value, { formattingOptions });
+        current = applyEdits(current, edits);
+    }
+    return current;
+}
+//# sourceMappingURL=structuredEditor.js.map

package/packages/server/dist/utils/structuredEditor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structuredEditor.js","sourceRoot":"","sources":["../../src/utils/structuredEditor.ts"],"names":[],"mappings":"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"}

package/packages/server/package.json

@@ -22,16 +22,19 @@
     "cookie-session": "^2.1.1",
     "cors": "^2.8.5",
     "express": "^4.21.0",
-    "express-rate-limit": "^8.3.1",
     "helmet": "^8.1.0",
     "i18next": "^24.2.3",
+    "ignore": "^5.3.2",
     "js-yaml": "^4.1.1",
+    "jsonc-parser": "^3.3.1",
+    "jszip": "^3.10.1",
     "multer": "^2.1.1",
     "node-pty": "^1.0.0",
     "sharp": "^0.34.5",
     "simple-git": "^3.27.0",
     "socket.io": "^4.8.0",
     "web-push": "^3.6.7",
+    "yaml": "^2.8.3",
     "zod": "^4.3.6"
   },
   "devDependencies": {

package/packages/server/resources/internals/INDEX.md

@@ -0,0 +1,23 @@
+# Hammoc Internals (Agent-Only Reference)
+
+This folder documents Hammoc's internal mechanisms that an in-IDE agent may need to read or correlate, but that are deliberately omitted from the user-facing manual. The user does not need to know any of this; the agent does.
+
+## How to use
+
+Read individual entries **on demand** when the user's request involves the underlying mechanism (for example: correlating an attached image with a file on disk, understanding how a session ID maps to a JSONL file). Do not pre-load this folder.
+
+## Entries
+
+- [Image Storage](./image-storage.md) — On-disk path and filename scheme for chat-attached images
+- [Harness File Layout](./harness-files.md) — Where `.claude/` items (skills, commands, agents, hooks, MCP servers, `CLAUDE.md`) live on disk, when changes take effect, and how the Secret-on-Shared guard relates to direct file writes
+
+## Maintenance
+
+Add a new file here whenever there is internal behavior the agent needs to act on but the user does not need to see. Likely future entries:
+
+- Session ID and project-path slug encoding under `~/.claude/projects/`
+- JSONL message tree structure (parent/child UUIDs, branching)
+- Permission-mode internal effects on the SDK call
+- Snippet resolution order and substitution rules
+
+Each new file should describe the on-disk reality (paths, formats, lifecycle), not the user-facing UI behavior — that belongs in the user manual.

package/packages/server/resources/internals/harness-files.md

@@ -0,0 +1,63 @@
+# Harness File Layout
+
+The Harness Workbench (user-facing, see manual §12) edits Claude Code's `.claude/` configuration trees in place. An agent can reach the same files directly with Read / Write / Edit and skip the UI when that's faster.
+
+## On-disk roots
+
+Two trees, walked in this priority order:
+
+```
+<projectRoot>/.claude/        # project scope (highest)
+<homeDir>/.claude/            # global scope (user scope)
+```
+
+When the same name (skill, command, agent, hook, MCP server, snippet) exists in both, the project copy is **active** and the global copy is **shadowed** but kept on disk.
+
+`<homeDir>` must be resolved before use — Read / Write / Edit do not expand `~`. On Windows that is `C:\Users\<user>\`.
+
+## Per-item layout
+
+| Item | Path (under either `.claude/` root) | Format |
+|------|--------------------------------------|--------|
+| Skill | `skills/<name>/SKILL.md` + bundle assets in the same directory | Markdown body + YAML frontmatter (`name`, `description`, `version`) |
+| Slash command | `commands/<name>.md` | Markdown body + YAML frontmatter |
+| Sub-agent | `agents/<name>.md` | Markdown body + YAML frontmatter (`name`, `description`, `tools`) |
+| Hook | `settings.json` → `hooks.<EventName>[]` entries | JSON; one event name per array key (`PreToolUse`, `PostToolUse`, `Stop`, `SubagentStop`, `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `PreCompact`, `Notification`) |
+| MCP server | `.mcp.json` at the project root, or `<homeDir>/.claude/.mcp.json` | JSON; entries under `mcpServers.<name>` |
+| `CLAUDE.md` | `<projectRoot>/.claude/CLAUDE.md`, `<homeDir>/.claude/CLAUDE.md` | Plain Markdown; both files load into every session, project wins on conflict |
+| Plugin | `plugins/<vendor>__<name>/` | Plugin bundle directory; treated read-only by Hammoc — copy items out to project/global to customize |
+
+Hammoc-native `%snippets` are a separate layer (see manual §4.6); they live under `<projectRoot>/.hammoc/snippets/` and `<homeDir>/.hammoc/snippets/`, **not** the `.claude/` tree.
+
+## Sharing scope
+
+Each file's "share" status is computed from the project's `.gitignore`:
+
+- **Shared** — File path is tracked by git
+- **Local** — File path is untracked but `.claude/` is not ignored
+- **Ignored** — A `.gitignore` rule excludes `.claude/` (or an ancestor)
+
+The workbench shows a badge for each file. When an agent writes a file under `.claude/`, the resulting share scope is whatever the `.gitignore` already says — Hammoc does not rewrite `.gitignore` on the agent's behalf.
+
+## Secret-on-Shared guard
+
+When the user saves a `Shared`-scope file through the UI, Hammoc scans for plaintext secrets (entropy + pattern heuristic) and blocks the save with a dialog. **An agent writing the file directly via Write / Edit bypasses that dialog.** If the agent is editing a `Shared` file under `.claude/`, it must avoid committing plaintext API keys, bearer tokens, etc. Use a sibling `*.local.<ext>` file (gitignored) and reference it from the shared file, or use `${ENV_VAR}` references that the hook / MCP runtime expands.
+
+## When changes take effect
+
+- **Skills, commands, agents, CLAUDE.md, snippets** — Picked up on the next message in a chat turn (the system prompt and tool list re-resolve on each turn).
+- **Hooks** — Same: next message in a chat turn.
+- **MCP servers** — Picked up only on a **fresh session spawn**, not mid-session. The workbench UI shows a "Takes effect on your next user message" banner with a "Start new session" button after the user edits an MCP entry; an agent making MCP edits should remind the user to start a new session, or do so on their behalf.
+- **Plugin enable/disable** — Same as MCP: fresh spawn required.
+
+## Static lint (informational)
+
+The workbench runs seven static-lint rules over the trees (see manual §12.12). Agents writing harness files should keep these rules in mind even though writes are not blocked:
+
+- duplicate names across scopes
+- invalid hook matcher regex
+- frontmatter / JSON parse errors
+- MCP `stdio` command not on `PATH`
+- malformed MCP URLs
+- non-standard agent tool names
+- hook bodies referencing undefined env vars

package/packages/server/resources/internals/image-storage.md

@@ -0,0 +1,43 @@
+# Image Storage
+
+When the user attaches an image to a chat message, Hammoc saves it under **Claude Code's per-project session data**, not inside the project being worked on. The user does not see this — they just attach and send. This document is for an agent that needs to read or correlate the file directly.
+
+## On-disk location
+
+```
+<homeDir>/.claude/projects/<encoded-project-path>/images/<sessionId>/<filename>
+```
+
+- `<homeDir>` — User home directory (Read/Edit tools do not expand `~`, so resolve to the absolute path first).
+- `<encoded-project-path>` — Claude Code's project slug. Path separators (`/`, `\`) and colons (`:`) in the original project path are replaced with hyphens. Example: `D:\repo\hammoc` → `D--repo-hammoc`.
+- `<sessionId>` — UUID of the chat session containing the message.
+- `<filename>` — `<sha256-prefix-16chars>.<ext>` for the original. Thumbnails use `<sha256-prefix-16chars>_thumb.<ext>`.
+- `<ext>` — One of `.png`, `.jpg`, `.gif`, `.webp`.
+
+## Supported MIME types
+
+| MIME | Extension |
+|---|---|
+| image/png | .png |
+| image/jpeg | .jpg |
+| image/gif | .gif |
+| image/webp | .webp |
+
+Anything else is rejected at attach time.
+
+## How an agent reaches these files
+
+- The chat message references each image via the API URL `/api/projects/<projectSlug>/sessions/<sessionId>/images/<filename>`. That URL is for the **browser** to render thumbnails — it is not a file-system path and Read tools cannot use it directly.
+- To open the file from disk, build the absolute path under `<homeDir>/.claude/projects/...` using the rules above, then call Read with that path.
+
+## Lifecycle
+
+- Images are written the moment the user sends a message with attachments.
+- A session's `images/<sessionId>/` directory is removed when the session itself is deleted.
+- Filenames are content-addressed (sha256 prefix), so attaching the same image bytes twice within a session reuses the same filename — automatic deduplication.
+
+## Limits
+
+- 5 images per message
+- 10 MB per image
+- Total per-session storage is bounded only by disk; there is no automatic eviction other than session deletion.

package/packages/server/resources/manual/01-getting-started.md

@@ -0,0 +1,104 @@
+## 1. Getting Started
+
+### 1.1 Installation
+
+**Option A: Run with npx (no install)**
+
+```bash
+npx hammoc
+```
+
+**Option B: Global install**
+
+```bash
+npm install -g hammoc
+hammoc
+```
+
+**Option C: From source (development)**
+
+```bash
+git clone https://github.com/starsh2001/hammoc.git
+cd hammoc
+npm install
+npm run dev
+```
+
+### 1.2 System Requirements
+
+- **Node.js** >= 18.0.0 (v22 LTS recommended)
+- **Claude Code CLI** installed and authenticated
+- Modern browser (Chrome, Firefox, Safari, Edge)
+
+### 1.3 First Launch
+
+1. Open http://localhost:3000 in your browser
+2. **Password Setup**: Set an admin password on first visit. This protects your instance from unauthorized access.
+3. **Login**: Enter your password to sign in. **"Stay signed in"** keeps you logged in for 30 days (checked by default). After too many failed attempts, login is temporarily locked with a countdown timer.
+4. **CLI Verification**: The onboarding wizard checks that Claude Code CLI is installed and authenticated. Follow the prompts if any step fails.
+5. **Project Selection**: Choose an existing Claude Code project or create a new one.
+
+### 1.4 Mobile Access
+
+Hammoc is fully responsive. From any device on the same network:
+
+```
+http://<your-computer-ip>:3000
+```
+
+- Desktop: Enter sends message, Shift+Enter for new line
+- Mobile (touch devices): Enter adds new line, tap the send button to send
+- **Pull-to-refresh**: Swipe down on the session list to refresh
+
+### 1.5 CLI Options
+
+```bash
+hammoc --port 8080          # Custom port
+hammoc --host localhost     # Bind to localhost only
+hammoc --trust-proxy        # Enable reverse proxy support
+hammoc --cors-origin <url>  # Restrict CORS to specific origin
+hammoc --reset-password     # Reset admin password
+hammoc --version            # Show version
+hammoc --help               # Show help
+```
+
+All options are also available as environment variables (see [Environment Variables](#14-environment-variables)).
+
+### 1.6 Remote Access (Reverse Proxy)
+
+If you need to expose Hammoc through a reverse proxy (Cloudflare Tunnel, nginx, etc.), use `--trust-proxy` and `--cors-origin`:
+
+```bash
+npx hammoc --trust-proxy --cors-origin https://hammoc.yourdomain.com
+```
+
+**What `--trust-proxy` enables:**
+- Reads real client IP from proxy headers for access control (e.g. localhost-only endpoints)
+- Sets session cookies with `Secure` flag (HTTPS-only)
+
+**What `--cors-origin` does:**
+- Restricts cross-origin requests to the specified URL only
+- Without it, any website can make authenticated requests to your Hammoc instance
+
+**Security features (always active, no configuration needed):**
+- Security headers (CSP, X-Frame-Options, HSTS, etc.)
+- Server management APIs (restart, update) restricted to localhost only
+- Terminal access restricted to local network IPs
+- Login brute-force protection (5 failed attempts → 30s lockout per IP)
+
+> **Note:** Hammoc does not apply request-level rate limiting itself — traffic shaping is an infrastructure concern. Configure it at your reverse proxy / WAF / API gateway (nginx `limit_req`, Cloudflare WAF rules, etc.).
+
+### 1.7 HTTPS / TLS
+
+Hammoc automatically enables HTTPS when TLS certificates are found:
+
+1. Place your certificate files in the `~/.hammoc/` directory:
+   - `~/.hammoc/key.pem` — Private key
+   - `~/.hammoc/cert.pem` — Certificate (or full chain)
+2. Restart Hammoc — it will detect the files and start an HTTPS server
+3. The startup log will show `TLS: enabled (certs from ~/.hammoc/)`
+
+If no certificates are found, the server runs over HTTP as usual.
+
+> **Tip:** For local development, you can generate self-signed certificates with `mkcert` or `openssl`. For production, use certificates from Let's Encrypt or your domain provider.
+