Job application tracker and AI-powered job search assistant. Helps job seekers manage their search journey with AI resume review, job matching, task logging, and application analytics, all while keeping your data private.
TypeScript ai-agentai-resume-analyzerapplication-trackerapplication-tracking-systematscareerjob-applicationjob-automationjob-huntingjob-searchjob-seeker-toolsjob-trackerjob-trackingjobsearchjobseekersmcpollamaresumeresume-reviewself-hosted
feat(wiki): add the OKF help bundle, its CI guard and GitHub wiki publishing
Khuram Niaz2025dbcd07a2
diff --git a/.github/workflows/wiki.yml b/.github/workflows/wiki.ymlnew file mode 100644index 0000000..21a6296--- /dev/null+++ b/.github/workflows/wiki.yml@@ -0,0 +1,46 @@+name: Publish Wiki++# One-way: wiki/ is the source, the GitHub wiki is a rendering of it. Set the+# wiki to collaborator-edit-only after the first successful publish so the two+# cannot diverge.+on:+ push:+ branches: [main]+ paths:+ - "wiki/**"+ - "src/lib/wiki/**"+ - "scripts/sync-wiki.mts"+ - ".github/workflows/wiki.yml"+ workflow_dispatch:++permissions:+ contents: write++concurrency:+ group: wiki+ cancel-in-progress: false++jobs:+ publish:+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@v4++ # 24, not the 20 that ci.yml and release.yml use: the sync script is a+ # .mts file run through Node's built-in TypeScript type stripping.+ - uses: actions/setup-node@v4+ with:+ node-version: 24+ cache: "npm"++ # The publisher's only runtime dependency is zod; skipping postinstall+ # avoids a Prisma generate this job has no use for.+ - run: npm ci --ignore-scripts++ # GITHUB_TOKEN's coverage of wiki repos is ambiguous in GitHub's docs.+ # If this 403s on push, add a PAT as the WIKI_TOKEN repo secret — no+ # change to this file is needed.+ - name: Sync wiki+ env:+ WIKI_TOKEN: ${{ secrets.WIKI_TOKEN || github.token }}+ run: node --disable-warning=MODULE_TYPELESS_PACKAGE_JSON scripts/sync-wiki.mtsdiff --git a/__tests__/wiki.spec.ts b/__tests__/wiki.spec.tsnew file mode 100644index 0000000..dd6d5a4--- /dev/null+++ b/__tests__/wiki.spec.ts@@ -0,0 +1,92 @@+import fs from "node:fs";+import path from "node:path";+import { parseWikiPage } from "@/lib/wiki/parse";+import { wikiIndexSchema, wikiPageSchema } from "@/lib/wiki/schema";+import { z } from "zod";++const WIKI_DIR = path.join(process.cwd(), "wiki");+const INDEX = "index.md";++function listMarkdown(dir: string, prefix = ""): string[] {+ return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {+ const rel = prefix ? `${prefix}/${entry.name}` : entry.name;+ if (entry.isDirectory()) return listMarkdown(path.join(dir, entry.name), rel);+ return entry.name.endsWith(".md") ? [rel] : [];+ });+}++// sort(): readdirSync is unordered, so without it the it.each test names+// shuffle between filesystems (Locked Decision #12).+const files = fs.existsSync(WIKI_DIR) ? listMarkdown(WIKI_DIR).sort() : [];+// log.md is OKF's reserved history file: prose, no frontmatter, not a page.+const pages = files.filter((f) => f !== INDEX && f !== "log.md");+const read = (rel: string) => fs.readFileSync(path.join(WIKI_DIR, rel), "utf8");++// it.each throws on an empty array, which would mask the real problem. The+// "contains the bundle root" test is what reports a missing or empty wiki/.+const eachPage = pages.length > 0 ? it.each(pages) : it.skip.each(["(none)"]);+const eachFile = files.length > 0 ? it.each(files) : it.skip.each(["(none)"]);++describe("wiki bundle", () => {+ it("contains the bundle root and at least one page", () => {+ expect(files).toContain(INDEX);+ expect(pages.length).toBeGreaterThan(0);+ });++ it("validates the bundle root against wikiIndexSchema", () => {+ const { frontmatter } = parseWikiPage(read(INDEX));+ const result = wikiIndexSchema.safeParse(frontmatter);+ expect(result.success, result.error && z.prettifyError(result.error)).toBe(true);+ });++ eachPage("%s parses and passes wikiPageSchema", (rel) => {+ const { frontmatter } = parseWikiPage(read(rel));+ const result = wikiPageSchema.safeParse(frontmatter);+ expect(result.success, result.error && z.prettifyError(result.error)).toBe(true);+ });++ eachPage("%s has unique H2 headings", (rel) => {+ const { headings } = parseWikiPage(read(rel));+ expect(headings.length).toBeGreaterThan(0);+ expect(new Set(headings).size).toBe(headings.length);+ });++ eachPage("%s phrases every H2 as a user question", (rel) => {+ const { headings } = parseWikiPage(read(rel));+ for (const heading of headings) {+ expect(heading.endsWith("?"), `"${heading}" in ${rel}`).toBe(true);+ }+ });++ eachPage("%s keeps sections under 300 words and the page under 2000", (rel) => {+ const body = parseWikiPage(read(rel)).body;+ const words = (text: string) => text.split(/\s+/).filter(Boolean).length;+ expect(words(body), rel).toBeLessThan(2000);+ for (const section of body.split(/^## /m).slice(1)) {+ const heading = section.split("\n")[0];+ expect(words(section), `${rel}: ## ${heading}`).toBeLessThan(300);+ }+ });++ eachFile("%s has no dead intra-wiki links", (rel) => {+ const body = parseWikiPage(read(rel)).body;+ const fromDir = path.posix.dirname(rel);+ for (const [, target] of body.matchAll(/\]\(([^)\s]+)\)/g)) {+ if (/^[a-z][a-z0-9+.-]*:/i.test(target) || target.startsWith("#")) continue;+ const [pathPart] = target.split("#");+ if (!pathPart.endsWith(".md")) continue;+ const resolved = path.posix.normalize(path.posix.join(fromDir, pathPart));+ expect(files, `${rel} -> ${target}`).toContain(resolved);+ }+ });++ it("links to every page from index.md exactly once", () => {+ const body = parseWikiPage(read(INDEX)).body;+ const linked = [...body.matchAll(/\]\(\.?\/?([^)\s#]+\.md)\)/g)].map((m) =>+ path.posix.normalize(m[1])+ );+ for (const page of pages) {+ expect(linked.filter((l) => l === page)).toHaveLength(1);+ }+ });+});diff --git a/__tests__/wikiParse.spec.ts b/__tests__/wikiParse.spec.tsnew file mode 100644index 0000000..57283b4--- /dev/null+++ b/__tests__/wikiParse.spec.ts@@ -0,0 +1,183 @@+import { parseWikiPage } from "@/lib/wiki/parse";+import { wikiIndexSchema, wikiPageSchema } from "@/lib/wiki/schema";++const PAGE = `---+type: how-to+title: Track a job application+description: Add a job manually or by pasting a posting into AI chat.+feature: jobs+tags: [jobs, applications, status]+aliases: [add a job, job board]+status: stable+stale_after: 2027-08-31+---++Intro line.++## How do I add a job?++Click Add Job.++## How do I export?++Click Export.+`;++describe("parseWikiPage", () => {+ it("reads scalars and inline arrays", () => {+ const { frontmatter } = parseWikiPage(PAGE);+ expect(frontmatter.type).toBe("how-to");+ expect(frontmatter.title).toBe("Track a job application");+ expect(frontmatter.tags).toEqual(["jobs", "applications", "status"]);+ expect(frontmatter.aliases).toEqual(["add a job", "job board"]);+ expect(frontmatter.stale_after).toBe("2027-08-31");+ });++ it("strips the frontmatter block from the body", () => {+ const { body } = parseWikiPage(PAGE);+ expect(body.startsWith("Intro line.")).toBe(true);+ expect(body).not.toContain("---");+ expect(body).not.toContain("type: how-to");+ });++ it("returns H2 headings in document order", () => {+ expect(parseWikiPage(PAGE).headings).toEqual([+ "How do I add a job?",+ "How do I export?",+ ]);+ });++ it("ignores H1, H3 and headings inside fenced code blocks", () => {+ const raw = `---+type: reference+---++# Page title++### Sub++\`\`\`markdown+## Not a real heading+\`\`\`++## Real heading+`;+ expect(parseWikiPage(raw).headings).toEqual(["Real heading"]);+ });++ it("strips matching surrounding quotes from a scalar", () => {+ const raw = `---+okf_version: "0.2"+---++Body.+`;+ expect(parseWikiPage(raw).frontmatter.okf_version).toBe("0.2");+ });++ it("returns an empty array for an empty inline array", () => {+ const raw = `---+type: reference+tags: []+---++Body.+`;+ expect(parseWikiPage(raw).frontmatter.tags).toEqual([]);+ });++ it("throws when the file does not open with a frontmatter fence", () => {+ expect(() => parseWikiPage("# No frontmatter\n")).toThrow(+ /must start with a frontmatter block/i+ );+ });++ it("throws when the frontmatter block is never closed", () => {+ expect(() => parseWikiPage("---\ntype: how-to\n")).toThrow(/unterminated/i);+ });++ it("throws on a line with no colon", () => {+ expect(() => parseWikiPage("---\ntype how-to\n---\n")).toThrow(+ /expected "key: value"/i+ );+ });++ it("throws on a block list, the grammar's deliberate limit", () => {+ const raw = `---+type: how-to+tags:+ - jobs+---+`;+ expect(() => parseWikiPage(raw)).toThrow(/expected "key: value"/i);+ });++ it("throws on a duplicate key", () => {+ expect(() => parseWikiPage("---\ntype: how-to\ntype: tutorial\n---\n")).toThrow(+ /duplicate key "type"/i+ );+ });+});++const VALID = {+ type: "how-to",+ title: "Track a job application",+ description: "Add a job manually or by pasting a posting into AI chat.",+ feature: "jobs",+ tags: ["jobs", "applications"],+};++describe("wikiPageSchema", () => {+ it("accepts a minimal valid page and defaults status to stable", () => {+ const parsed = wikiPageSchema.parse(VALID);+ expect(parsed.status).toBe("stable");+ expect(parsed.aliases).toBeUndefined();+ });++ it("accepts every optional field", () => {+ const parsed = wikiPageSchema.parse({+ ...VALID,+ aliases: ["job board"],+ status: "draft",+ stale_after: "2027-08-31",+ });+ expect(parsed.stale_after).toBe("2027-08-31");+ });++ it("rejects a type outside the Diataxis vocabulary", () => {+ expect(wikiPageSchema.safeParse({ ...VALID, type: "guide" }).success).toBe(false);+ });++ it("rejects an unknown feature area", () => {+ expect(wikiPageSchema.safeParse({ ...VALID, feature: "billing" }).success).toBe(false);+ });++ it("rejects an empty tags array", () => {+ expect(wikiPageSchema.safeParse({ ...VALID, tags: [] }).success).toBe(false);+ });++ it("rejects a misspelled key rather than ignoring it", () => {+ expect(wikiPageSchema.safeParse({ ...VALID, tag: ["jobs"] }).success).toBe(false);+ });++ it("rejects a non-ISO stale_after", () => {+ expect(+ wikiPageSchema.safeParse({ ...VALID, stale_after: "31/08/2027" }).success+ ).toBe(false);+ });++ it("validates real parser output end to end", () => {+ const { frontmatter } = parseWikiPage(PAGE);+ expect(wikiPageSchema.parse(frontmatter).feature).toBe("jobs");+ });+});++describe("wikiIndexSchema", () => {+ it("accepts the bundle root", () => {+ expect(wikiIndexSchema.parse({ okf_version: "0.2" }).okf_version).toBe("0.2");+ });++ it("rejects a page-shaped frontmatter", () => {+ expect(wikiIndexSchema.safeParse(VALID).success).toBe(false);+ });+});diff --git a/__tests__/wikiPublish.spec.ts b/__tests__/wikiPublish.spec.tsnew file mode 100644index 0000000..7bb14fc--- /dev/null+++ b/__tests__/wikiPublish.spec.ts@@ -0,0 +1,106 @@+import {+ buildSidebar,+ rewriteWikiLinks,+ toWikiFileName,+ toWikiPageName,+} from "@/lib/wiki/publish";++describe("toWikiPageName", () => {+ it("maps the bundle root to Home", () => {+ expect(toWikiPageName("index.md")).toBe("Home");+ });++ it("capitalises each hyphen-separated word", () => {+ expect(toWikiPageName("getting-started.md")).toBe("Getting-Started");+ });++ it("handles a single-word page", () => {+ expect(toWikiPageName("jobs.md")).toBe("Jobs");+ });++ it("joins nested path segments with a hyphen", () => {+ expect(toWikiPageName("jobs/csv-export.md")).toBe("Jobs-CSV-Export");+ });++ it("maps a nested index to its directory, not to Jobs-Index", () => {+ expect(toWikiPageName("jobs/index.md")).toBe("Jobs");+ });++ it("upper-cases known acronyms", () => {+ expect(toWikiPageName("ai-setup.md")).toBe("AI-Setup");+ expect(toWikiPageName("mcp-server.md")).toBe("MCP-Server");+ expect(toWikiPageName("pdf-export.md")).toBe("PDF-Export");+ expect(toWikiPageName("ats-sources.md")).toBe("ATS-Sources");+ });++ it("appends .md for the wiki filename", () => {+ expect(toWikiFileName("getting-started.md")).toBe("Getting-Started.md");+ expect(toWikiFileName("index.md")).toBe("Home.md");+ });+});++describe("rewriteWikiLinks", () => {+ it("rewrites a ./ relative link to the wiki page name", () => {+ expect(rewriteWikiLinks("See [Jobs](./jobs.md).")).toBe("See [Jobs](Jobs).");+ });++ it("rewrites a bare relative link", () => {+ expect(rewriteWikiLinks("See [Start](getting-started.md).")).toBe(+ "See [Start](Getting-Started)."+ );+ });++ it("preserves an anchor fragment", () => {+ expect(rewriteWikiLinks("[x](./jobs.md#how-do-i-add-a-job)")).toBe(+ "[x](Jobs#how-do-i-add-a-job)"+ );+ });++ it("rewrites the bundle root to Home", () => {+ expect(rewriteWikiLinks("[Index](./index.md)")).toBe("[Index](Home)");+ });++ it("resolves a sibling link from a nested page", () => {+ expect(rewriteWikiLinks("[Sib](./csv-export.md)", "jobs")).toBe(+ "[Sib](Jobs-CSV-Export)"+ );+ });++ it("leaves external links alone", () => {+ const raw = "[repo](https://github.com/Gsync/jobsync) and [d](http://x.dev/a.md)";+ expect(rewriteWikiLinks(raw)).toBe(raw);+ });++ it("leaves a pure anchor link alone", () => {+ expect(rewriteWikiLinks("[top](#how-do-i-add-a-job)")).toBe(+ "[top](#how-do-i-add-a-job)"+ );+ });++ it("leaves image and non-markdown targets alone", () => {+ expect(rewriteWikiLinks("[shot](./screenshot.png)")).toBe("[shot](./screenshot.png)");+ });+});++describe("buildSidebar", () => {+ it("lists Home first, then every linked page in index order", () => {+ const body = `# JobSync Help++- [Getting Started](Getting-Started) — first run.+- [Jobs](Jobs) — track applications.+`;+ expect(buildSidebar(body)).toBe(+ `### JobSync Help++- [Home](Home)+- [Getting Started](Getting-Started)+- [Jobs](Jobs)+`+ );+ });++ it("ignores prose lines and inline links outside the list", () => {+ const body = "Intro with a [link](Jobs).\n\n- [Jobs](Jobs) — track.\n";+ expect(buildSidebar(body)).toBe("### JobSync Help\n\n- [Home](Home)\n- [Jobs](Jobs)\n");+ });+});diff --git a/scripts/sync-wiki.mts b/scripts/sync-wiki.mtsnew file mode 100644index 0000000..f247289--- /dev/null+++ b/scripts/sync-wiki.mts@@ -0,0 +1,123 @@+// Renders wiki/ into the GitHub wiki repo. Run by .github/workflows/wiki.yml+// as: node --disable-warning=MODULE_TYPELESS_PACKAGE_JSON scripts/sync-wiki.mts+//+// Imports carry .ts extensions because Node's type stripping is ESM and needs+// explicit ones. tsconfig excludes scripts/, so tsc never sees these. Pass+// --dry-run to validate and print without cloning or pushing.++import { execFileSync } from "node:child_process";+import fs from "node:fs";+import os from "node:os";+import path from "node:path";+import { z } from "zod";+import { parseWikiPage } from "../src/lib/wiki/parse.ts";+import { wikiIndexSchema, wikiPageSchema } from "../src/lib/wiki/schema.ts";+import {+ buildSidebar,+ rewriteWikiLinks,+ toWikiFileName,+} from "../src/lib/wiki/publish.ts";++const WIKI_DIR = path.join(process.cwd(), "wiki");+const INDEX = "index.md";+const DRY_RUN = process.argv.includes("--dry-run");++function listMarkdown(dir: string, prefix = ""): string[] {+ return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {+ const rel = prefix ? `${prefix}/${entry.name}` : entry.name;+ if (entry.isDirectory()) return listMarkdown(path.join(dir, entry.name), rel);+ return entry.name.endsWith(".md") ? [rel] : [];+ });+}++function render(): { files: Map<string, string>; sidebar: string } {+ // sort(): readdirSync is unordered, and an unsorted render reorders the+ // published wiki commit for no reason (Locked Decision #12).+ const sources = listMarkdown(WIKI_DIR).sort();+ const errors: string[] = [];+ const files = new Map<string, string>();+ let indexBody = "";++ for (const rel of sources) {+ const raw = fs.readFileSync(path.join(WIKI_DIR, rel), "utf8");+ let parsed;+ try {+ parsed = parseWikiPage(raw);+ } catch (error) {+ errors.push(`${rel}: ${(error as Error).message}`);+ continue;+ }++ const schema = rel === INDEX ? wikiIndexSchema : wikiPageSchema;+ const result = schema.safeParse(parsed.frontmatter);+ if (!result.success) {+ errors.push(`${rel}:\n${z.prettifyError(result.error)}`);+ continue;+ }++ const body = rewriteWikiLinks(parsed.body, path.posix.dirname(rel));+ files.set(toWikiFileName(rel), body);+ if (rel === INDEX) indexBody = body;+ }++ if (errors.length > 0) {+ console.error(`Wiki validation failed (${errors.length}):\n\n${errors.join("\n\n")}`);+ process.exit(1);+ }++ return { files, sidebar: buildSidebar(indexBody) };+}++function git(cwd: string, ...args: string[]): string {+ return execFileSync("git", args, { cwd, encoding: "utf8" });+}++function publish(files: Map<string, string>, sidebar: string): void {+ const repository = process.env.GITHUB_REPOSITORY;+ const token = process.env.WIKI_TOKEN;+ if (!repository || !token) {+ console.error("GITHUB_REPOSITORY and WIKI_TOKEN must both be set.");+ process.exit(1);+ }++ const remote = `https://x-access-token:${token}@github.com/${repository}.wiki.git`;+ const checkout = fs.mkdtempSync(path.join(os.tmpdir(), "jobsync-wiki-"));+ // Never log `remote`: it carries the token.+ git(process.cwd(), "clone", "--depth", "1", remote, checkout);++ for (const name of fs.readdirSync(checkout)) {+ if (name === ".git") continue;+ fs.rmSync(path.join(checkout, name), { recursive: true, force: true });+ }+ for (const [name, body] of files) {+ fs.writeFileSync(path.join(checkout, name), body, "utf8");+ }+ fs.writeFileSync(path.join(checkout, "_Sidebar.md"), sidebar, "utf8");++ git(checkout, "add", "-A");+ if (git(checkout, "status", "--porcelain").trim() === "") {+ console.log("Wiki already up to date; nothing to push.");+ return;+ }++ git(checkout, "config", "user.name", "github-actions[bot]");+ git(+ checkout,+ "config",+ "user.email",+ "41898282+github-actions[bot]@users.noreply.github.com"+ );+ git(checkout, "commit", "-m", `docs(wiki): sync from ${process.env.GITHUB_SHA ?? "wiki/"}`);+ git(checkout, "push", "origin", "HEAD");+ console.log(`Published ${files.size} pages plus _Sidebar.md.`);+}++const { files, sidebar } = render();++if (DRY_RUN) {+ console.log(`Validated ${files.size} pages:\n`);+ for (const name of files.keys()) console.log(` ${name}`);+ console.log(`\n_Sidebar.md:\n\n${sidebar}`);+} else {+ publish(files, sidebar);+}diff --git a/src/lib/wiki/parse.ts b/src/lib/wiki/parse.tsnew file mode 100644index 0000000..92074d6--- /dev/null+++ b/src/lib/wiki/parse.ts@@ -0,0 +1,87 @@+// Read by scripts/sync-wiki.mts at build time and by __tests__/wiki.spec.ts.+// Nothing under src/app imports it yet — the help tool that will is deferred.+// A future dead-code sweep should not delete this directory.+//+// Imports nothing on purpose: the sync script runs this file directly under+// Node's TypeScript type stripping, where a relative import would need a .ts+// extension that `tsc --noEmit` would then reject.++export type RawFrontmatter = Record<string, string | string[]>;++export interface ParsedWikiPage {+ frontmatter: RawFrontmatter;+ body: string;+ headings: string[];+}++const FENCE = "---";++function unquote(value: string): string {+ const first = value[0];+ const last = value[value.length - 1];+ if (value.length >= 2 && (first === '"' || first === "'") && first === last) {+ return value.slice(1, -1);+ }+ return value;+}++function parseValue(raw: string): string | string[] {+ const value = raw.trim();+ if (value.startsWith("[") && value.endsWith("]")) {+ const inner = value.slice(1, -1).trim();+ if (inner === "") return [];+ return inner.split(",").map((item) => unquote(item.trim()));+ }+ return unquote(value);+}++function extractHeadings(body: string): string[] {+ const headings: string[] = [];+ let inFence = false;+ for (const line of body.split("\n")) {+ if (line.trimStart().startsWith("```")) {+ inFence = !inFence;+ continue;+ }+ if (!inFence && line.startsWith("## ")) {+ headings.push(line.slice(3).trim());+ }+ }+ return headings;+}++export function parseWikiPage(raw: string): ParsedWikiPage {+ const lines = raw.replace(/\r\n/g, "\n").split("\n");+ if (lines[0]?.trim() !== FENCE) {+ throw new Error('Page must start with a frontmatter block ("---")');+ }++ const frontmatter: RawFrontmatter = {};+ let close = -1;+ for (let i = 1; i < lines.length; i++) {+ const line = lines[i];+ if (line.trim() === FENCE) {+ close = i;+ break;+ }+ if (line.trim() === "") continue;+ const colon = line.indexOf(":");+ if (colon <= 0 || line !== line.trimStart()) {+ throw new Error(`Frontmatter line ${i + 1}: expected "key: value", got: ${line}`);+ }+ const key = line.slice(0, colon).trim();+ // Object.hasOwn, not `in`: "constructor" in {} is true, so `in` would+ // throw a bogus duplicate-key error for a page with a key of that name.+ if (Object.hasOwn(frontmatter, key)) {+ throw new Error(`Frontmatter duplicate key "${key}"`);+ }+ frontmatter[key] = parseValue(line.slice(colon + 1));+ }++ if (close === -1) {+ throw new Error('Unterminated frontmatter block: no closing "---"');+ }++ const body = lines.slice(close + 1).join("\n").replace(/^\n+/, "");+ return { frontmatter, body, headings: extractHeadings(body) };+}diff --git a/src/lib/wiki/publish.ts b/src/lib/wiki/publish.tsnew file mode 100644index 0000000..6cab2ea--- /dev/null+++ b/src/lib/wiki/publish.ts@@ -0,0 +1,69 @@+import path from "node:path";++// Symptom when one is missing: the published page title reads "Ai" not "AI".+export const WIKI_ACRONYMS: Record<string, string> = {+ ai: "AI",+ mcp: "MCP",+ pdf: "PDF",+ csv: "CSV",+ ats: "ATS",+};++function capitalise(word: string): string {+ const acronym = WIKI_ACRONYMS[word.toLowerCase()];+ if (acronym) return acronym;+ return word.charAt(0).toUpperCase() + word.slice(1);+}++// GitHub renders a "-" in a wiki filename as a space, so Getting-Started.md+// publishes as the page "Getting Started".+export function toWikiPageName(relPath: string): string {+ const normalised = relPath.replace(/\\/g, "/").replace(/^\.\//, "");+ const withoutExt = normalised.replace(/\.md$/i, "");+ const segments = withoutExt.split("/").filter(Boolean);++ // A directory's index is that directory's page, not "<Dir>-Index".+ if (segments[segments.length - 1] === "index") {+ segments.pop();+ if (segments.length === 0) return "Home";+ }++ return segments+ .flatMap((segment) => segment.split("-"))+ .filter(Boolean)+ .map(capitalise)+ .join("-");+}++export function toWikiFileName(relPath: string): string {+ return `${toWikiPageName(relPath)}.md`;+}++const MARKDOWN_LINK = /\]\(([^)\s]+)\)/g;++// Publisher-side rewriting only. The deferred help tool needs the opposite+// transform (link -> label text), because renderAgentMarkdown disables links.+//+// Deliberately fence-blind, unlike extractHeadings: a link inside a fenced+// example is rewritten too. Cosmetic, and only on the published copy.+export function rewriteWikiLinks(body: string, fromDir = ""): string {+ return body.replace(MARKDOWN_LINK, (match, target: string) => {+ if (/^[a-z][a-z0-9+.-]*:/i.test(target) || target.startsWith("#")) return match;+ const [pathPart, fragment] = target.split("#");+ if (!/\.md$/i.test(pathPart)) return match;+ const resolved = path.posix.normalize(path.posix.join(fromDir, pathPart));+ return `](${toWikiPageName(resolved)}${fragment ? `#${fragment}` : ""})`;+ });+}++const SIDEBAR_ITEM = /^\s*[-*]\s+\[([^\]]+)\]\(([^)\s]+)\)/;++export function buildSidebar(rewrittenIndexBody: string): string {+ const items = rewrittenIndexBody+ .split("\n")+ .map((line) => SIDEBAR_ITEM.exec(line))+ .filter((match): match is RegExpExecArray => match !== null)+ .map((match) => `- [${match[1]}](${match[2]})`);++ return `### JobSync Help\n\n- [Home](Home)\n${items.join("\n")}\n`;+}diff --git a/src/lib/wiki/schema.ts b/src/lib/wiki/schema.tsnew file mode 100644index 0000000..ab717e2--- /dev/null+++ b/src/lib/wiki/schema.ts@@ -0,0 +1,43 @@+import { z } from "zod";++// Diataxis plus troubleshooting. OKF leaves the type vocabulary open.+export const WIKI_TYPES = [+ "tutorial",+ "how-to",+ "reference",+ "explanation",+ "troubleshooting",+] as const;++// The pre-filter a retrieval layer narrows on before ranking anything.+export const WIKI_FEATURES = [+ "setup",+ "jobs",+ "automations",+ "profile",+ "ai",+ "tasks",+ "questions",+] as const;++export const WIKI_STATUSES = ["draft", "stable", "deprecated"] as const;++// strict(): a typo'd key fails a PR instead of vanishing from a future filter.+export const wikiPageSchema = z+ .object({+ type: z.enum(WIKI_TYPES),+ title: z.string().min(1),+ description: z.string().min(1),+ feature: z.enum(WIKI_FEATURES),+ tags: z.array(z.string().min(1)).min(1),+ aliases: z.array(z.string().min(1)).optional(),+ status: z.enum(WIKI_STATUSES).default("stable"),+ stale_after: z.iso.date().optional(),+ })+ .strict();++// The bundle root carries no type/title/feature, so it needs its own schema+// rather than making every page field optional.+export const wikiIndexSchema = z.object({ okf_version: z.literal("0.2") }).strict();++export type WikiFrontmatter = z.infer<typeof wikiPageSchema>;diff --git a/wiki/getting-started.md b/wiki/getting-started.mdnew file mode 100644index 0000000..ce9ce12--- /dev/null+++ b/wiki/getting-started.md@@ -0,0 +1,45 @@+---+type: tutorial+title: Getting Started+description: The first run through JobSync — creating an account, connecting an AI provider, adding a job, and what each sidebar area is for.+feature: setup+tags: [setup, first run, sign in, account, ai provider, ollama, sidebar, navigation]+aliases: [new user, onboarding, first steps, how do I start, set up jobsync]+status: stable+stale_after: 2027-08-31+---++# Getting Started++## How do I create an account and sign in?++Open the app and choose **Create Account** on the sign-in page, or go straight to `/signup`. JobSync accounts are local to your installation — there is no external identity provider and no email verification step, so the account you create is immediately usable. After signing up you land on the Dashboard at `/dashboard`. To sign in later, use `/signin` with the same email and password.++## How do I connect an AI provider?++Open the avatar menu at the bottom of the left sidebar and choose **Settings**, then **AI Provider**. Pick a provider, then a model. JobSync supports Ollama, OpenAI, DeepSeek, Gemini and OpenRouter. Ollama runs models on your own machine and needs no key; the other four are hosted and need an API key, which you add under **Settings → API Keys** in that same menu. Keys are encrypted before they are stored.++Nothing AI-powered works until a provider *and* a model are both set — resume review, job matching, cover letters and the chat panel all refuse to start rather than silently picking a model for you. If you selected Ollama and the model list is empty, JobSync could not reach the Ollama server; check that it is running and reachable from wherever JobSync is running.++## How do I add my first job?++Click **Jobs** in the sidebar, then the **Add Job** button in the top-right of the Jobs card. Job Title, Company, Job Location and Job Source are the fields you have to fill in yourself. Job Type, Workplace Type, Status, Due Date, Salary Range and Job Description are also required, but the form arrives with them already filled — Due Date three days out and Job Description the placeholder `N/A` — so you can change them but not leave them empty. Job URL, Date Applied, a resume, a cover letter and skills are the genuinely optional ones, and you can add them later.++There is a faster route once an AI provider is set: click **Chat AI** in the header, paste the full text of a job posting into the chat, and the assistant extracts the details and shows you exactly what it found before anything is saved. Nothing is written until you approve it.++## What is each area of the sidebar for?++- **Dashboard** — summary cards: application counts, recent jobs and activities, and weekly charts.+- **Jobs** — every job you are tracking, plus jobs discovered by automations.+- **Automations** — scheduled searches that pull new postings in and score them against your resume.+- **Tasks** — to-dos with a due date, priority and percent complete, optionally linked to a job.+- **Activities** — time logged against jobs and tasks, with a calendar view.+- **Questions** — a question bank for interview preparation.+- **Profile** — your resumes, contact information and the profile the AI features read from.+- **Library** — the shared reference lists behind the dropdowns: Companies, Job Titles, Locations, Sources, Skills and Activity Types.++**Settings is not one of the entries above.** Open the avatar menu at the bottom of the sidebar instead, below the navigation list, and choose **Settings**. It holds AI Provider, API Keys, Appearance, MCP Access and Data (backup, export and import). That same menu also has Support and Logout.++## Where do I find installation and Docker instructions?++They are in the [project README](https://github.com/Gsync/jobsync#readme), not here. That covers running JobSync with Docker, the environment variables it reads, and how to upgrade an existing installation. These wiki pages assume you already have a running instance and cover using it.diff --git a/wiki/index.md b/wiki/index.mdnew file mode 100644index 0000000..6061285--- /dev/null+++ b/wiki/index.md@@ -0,0 +1,12 @@+---+okf_version: "0.2"+---++# JobSync Help++JobSync tracks job applications, resumes and the work you do around them. These pages cover how to use it.++- [Getting Started](./getting-started.md) — create an account, connect an AI provider, add your first job, and what each area of the app is for.+- [Jobs](./jobs.md) — add jobs manually or by pasting a posting into AI chat, move them through the status workflow, edit, filter, export and delete them.++Installation, Docker and environment variables are in the [project README](https://github.com/Gsync/jobsync#readme).diff --git a/wiki/jobs.md b/wiki/jobs.mdnew file mode 100644index 0000000..74804dc--- /dev/null+++ b/wiki/jobs.md@@ -0,0 +1,52 @@+---+type: how-to+title: Jobs+description: Adding jobs by hand or by pasting a posting into AI chat, moving them through the status workflow, and finding, editing, exporting or deleting them.+feature: jobs+tags: [jobs, applications, add a job, status, applied, interview, offer, rejected, csv, export, paste, filter, search]+aliases: [job tracker, application tracker, my jobs, job board, track an application, job list]+status: stable+stale_after: 2027-08-31+---++# Jobs++## How do I add a job manually?++Open **Jobs** in the sidebar and click **Add Job** at the top-right of the Jobs card. Job Title, Company, Job Location and Job Source are the fields you must fill in — each is a combo box that either picks an existing entry or creates a new one as you type, and Location and Source come pre-selected with whatever you used on your last job.++Job Type, Workplace Type, Status, Due Date, Salary Range and Job Description are required too, but the form opens with them already set — Job Type on its first option, Workplace Type on Onsite, Status on Draft, Due Date three days from today, Salary Range `1` and Job Description the placeholder `N/A`. You can change any of them; you cannot clear them. Genuinely optional are Job URL, the Applied switch, Date Applied, a resume and cover letter to attach, and skills.++Paste the full posting text into Job Description if you have it. The AI features — resume review, job match and cover letter generation — read that field, and a job saved with only a title and a salary gives them almost nothing to work from.++## How do I add a job by pasting a posting into AI chat?++Click **Chat AI** in the header to open the assistant panel, paste the full text of a job posting into the message box, and send it. The assistant extracts the title, company, location and description and shows you an approval card with exactly what it found. Nothing is saved to your tracker until you approve that card, and you can edit the details before you do.++This requires an AI provider and model to be set under **Settings → AI Provider**; without them the panel tells you so instead of starting. A long paste is attached as a chip rather than inlined into the message — that is expected, and the full text still reaches the extraction.++## What do the job statuses mean?++A job carries exactly one status from: **New**, **Draft**, **Applied**, **Interview**, **Offer**, **Rejected**, **Expired** and **Archived**. They are labels you move by hand, not a state machine — nothing stops you going from Interview back to Draft, and nothing changes a status on your behalf.++*New* is where a job discovered by an automation starts. *Draft* is a job you have entered but not applied to. *Applied* through *Offer* track a live application. *Expired* is for a posting that closed before you acted; *Archived* is for anything you want out of the way without deleting it.++## How do I change a job's status?++Open the job from the Jobs list, click the **⋮** menu at the top-right of the job details, and choose **Change status** — the submenu lists every status, with the current one greyed out. The change saves immediately; there is no separate save step.++The Add Job dialog also has a Status field, so a status can be set when you first create the job or from **Edit Job** later.++## How do I edit, annotate or delete a job?++All three are in the **⋮** menu on the job details page. **Edit Job** reopens the same dialog you added it with, pre-filled. **Add a Note** attaches a note to the job. **Delete** asks for confirmation and then removes the job permanently — there is no undo and no trash, so use *Archived* status instead if you only want it out of the list.++## How do I find a job in a long list?++The Jobs card header has three tools. The **search box** matches on job text. The **filter dropdown** narrows to a preset: All (Except Dismissed), Applied, Interview, Draft, Rejected, Part-time, Accepted (discovered) or Dismissed (discovered). Clicking a company, title, location or source anywhere in the list adds it as a filter chip next to the search box — click the chip's **×** to clear it.++The list also has a view toggle for table or card layout, and a reload button that refetches without a full page refresh.++## How do I export my jobs to CSV?++Click **Export** in the Jobs card header. Your jobs download as a CSV file named `jobsync-YYYY-MM-DD.csv`. The export covers your jobs, not the reference lists behind them — for a complete, restorable copy of everything including resumes, tasks and activities, use **Settings → Data** instead.