npm - openwriter - Versions diffs - 0.29.1 → 0.30.0 - Mend

openwriter 0.29.1 → 0.30.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/dist/client/assets/index-BtCWWQrZ.css +1 -0
package/dist/client/assets/{index-DHaZI7nA.js → index-D1naX68L.js} +52 -52
package/dist/client/index.html +2 -2
package/dist/plugins/authors-voice/dist/index.d.ts +5 -1
package/dist/plugins/authors-voice/dist/index.js +24 -1
package/dist/plugins/github/dist/blog-tools.d.ts +58 -1
package/dist/plugins/github/dist/blog-tools.js +337 -17
package/dist/plugins/github/dist/helpers.d.ts +23 -0
package/dist/plugins/github/dist/helpers.js +2 -0
package/dist/plugins/publish/dist/index.js +6 -1
package/package.json +3 -2
package/dist/client/assets/index-Gdw1m46J.css +0 -1

package/dist/client/index.html CHANGED Viewed

@@ -10,8 +10,8 @@
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link href="https://fonts.googleapis.com/css2?family=Charter:ital,wght@0,400;0,700;1,400&family=Crimson+Pro:ital,wght@0,300;0,400;0,600;0,700;1,400&family=DM+Sans:ital,wght@0,400;0,500;0,600;0,700;1,400&family=DM+Serif+Display&family=IBM+Plex+Mono:wght@400;500;600&family=IBM+Plex+Sans:wght@400;500;600&family=Inter:wght@400;500;600;700&family=Libre+Baskerville:ital,wght@0,400;0,700;1,400&family=Literata:ital,opsz,wght@0,7..72,400;0,7..72,600;0,7..72,700;1,7..72,400&family=Newsreader:ital,opsz,wght@0,6..72,400;0,6..72,600;1,6..72,400&family=Playfair+Display:wght@400;600;700;900&family=Source+Serif+4:ital,opsz,wght@0,8..60,400;0,8..60,600;0,8..60,700;1,8..60,400&family=Space+Grotesk:wght@400;500;600;700&family=Space+Mono:wght@400;700&display=swap" rel="stylesheet" />
-    <script type="module" crossorigin src="/assets/index-DHaZI7nA.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-Gdw1m46J.css">
+    <script type="module" crossorigin src="/assets/index-D1naX68L.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-BtCWWQrZ.css">
   </head>
   <body>
     <div id="root"></div>

package/dist/plugins/authors-voice/dist/index.d.ts CHANGED Viewed

@@ -8,10 +8,14 @@
  */
 import type { Express } from 'express';
 interface PluginConfigField {
-    type: 'string' | 'number' | 'boolean';
+    type: 'string' | 'number' | 'boolean' | 'select';
     required?: boolean;
     env?: string;
     description?: string;
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
 }
 interface PluginRouteContext {
     app: Express;

package/dist/plugins/authors-voice/dist/index.js CHANGED Viewed

@@ -23,11 +23,27 @@ const plugin = {
             env: 'AV_BACKEND_URL',
             description: 'AV backend URL',
         },
+        // Model tier for rewrites. Sent as `modelTier` on /api/voice/* (the AV API owns the
+        // tier→model map + default — this is a pure pass-through of the user's pick). Blank =
+        // API default (strongest). Labels mirror the API's TIER_PICKER_OPTIONS.
+        'model': {
+            type: 'select',
+            env: 'AV_MODEL_TIER',
+            description: 'Writing model',
+            options: [
+                { value: '', label: 'Default (Strongest)' },
+                { value: 'strongest', label: 'Strongest — Claude Opus (best quality)' },
+                { value: 'gemini-pro', label: 'Gemini Pro — flagship, strong + cheap' },
+                { value: 'balanced', label: 'Balanced — Claude Sonnet' },
+                { value: 'fast', label: 'Fast — Gemini Flash (cheapest)' },
+            ],
+        },
     },
     registerRoutes(ctx) {
         const backendUrl = ctx.config['backend-url'] || process.env.AV_BACKEND_URL || 'https://authors-voice.com';
         const apiKey = ctx.config['api-key'] || process.env.AV_API_KEY || '';
         const debugEnabled = process.env.AV_DEBUG === '1' || process.env.AV_DEBUG === 'true';
+        const modelTier = ctx.config['model'] || process.env.AV_MODEL_TIER || '';
         const authHeaders = () => {
             const h = { 'Content-Type': 'application/json' };
             if (apiKey)
@@ -39,6 +55,13 @@ const plugin = {
                 return body;
             return { ...body, debug: true };
         };
+        // Inject the user's model-tier pick. Pure pass-through: the AV API validates the slug
+        // and falls back to its own default if absent/unknown. Blank → nothing injected.
+        const withModel = (body) => {
+            if (!modelTier || !body || typeof body !== 'object')
+                return body;
+            return { ...body, modelTier };
+        };
         // Wildcard proxy for /api/voice/* routes. Pure pass-through: the AV API owns the
         // engine choice (v1/v2) via its own AV_DEFAULT_ENGINE setting, so the plugin injects
         // nothing but the optional owner-only dev debug flag.
@@ -46,7 +69,7 @@ const plugin = {
             try {
                 const subPath = req.params[0] || '';
                 const targetUrl = `${backendUrl}/api/voice/${subPath}`;
-                const body = withDebug(req.body);
+                const body = withModel(withDebug(req.body));
                 console.log(`[AV Plugin] ${req.method} ${req.path} → ${targetUrl}`);
                 const upstream = await fetch(targetUrl, {
                     method: 'POST',

package/dist/plugins/github/dist/blog-tools.d.ts CHANGED Viewed

@@ -4,5 +4,62 @@
  * Auth: piggybacks on the user's existing `gh auth login`.
  * Persistence: blogSites in plugins['@openwriter/plugin-github'].blogSites.
  */
-import { type PluginMcpTool } from './helpers.js';
+import { type BlogSite, type PluginMcpTool } from './helpers.js';
+/**
+ * Derive the per-site image contract from sampled posts:
+ *  - `image_field`        — which frontmatter key holds the cover
+ *  - `image_path_style`   — do values carry a leading slash?
+ *  - `image_public_prefix`— the dominant directory the images live under
+ *                           (relative, no leading slash)
+ *  - `image_naming`       — `og-{slug}` vs `{slug}` filename convention
+ *                           (detected by the dominant basename shape)
+ * Conservative: only the dominant local-path field is analyzed; full URLs
+ * are ignored. Anything not confidently detected is left undefined so
+ * post_to_blog falls back to its documented defaults.
+ */
+export declare function inferImageConventions(samples: Array<{
+    fm: Record<string, string>;
+    slug: string;
+}>): {
+    image_field?: string;
+    image_path_style?: 'relative' | 'absolute';
+    image_public_prefix?: string;
+    image_naming?: string;
+};
+/** Site's effective path style. Absent ⇒ legacy "absolute". */
+export declare function pathStyleOf(site: Pick<BlogSite, 'image_path_style'>): 'relative' | 'absolute';
+/**
+ * Public reference for one image file under the site's prefix, honoring the
+ * site's path style. The prefix is normalized (leading + trailing slashes
+ * stripped) so storage is style-agnostic — `style` alone decides the leading
+ * slash, which makes the contract unambiguous regardless of how the prefix
+ * was saved (`/images/og` vs `images/og` both behave identically).
+ *   relative → "images/og/x.png"   absolute → "/images/og/x.png"
+ */
+export declare function imageRef(publicPrefix: string, file: string, style: 'relative' | 'absolute'): string;
+/**
+ * Resolve the deterministic cover filename from the site's naming template.
+ *   `{slug}` → post slug
+ *   `{ext}`  → source extension, no dot (preserved from the original)
+ * A template carrying a literal extension and no `{ext}` placeholder
+ * (e.g. `og-{slug}.png`) is respected as authored. Absent template ⇒
+ * `og-{slug}.{ext}`.
+ */
+export declare function coverFilename(template: string | undefined, slug: string, sourceExt: string): string;
+/**
+ * Build the YAML frontmatter from blogContext + site defaults.
+ *
+ * Order of precedence (low → high):
+ *   1. Site `frontmatter_defaults` (e.g. `layout`, `author`, `prerender`)
+ *   2. Generated `title` (from document title — always present)
+ *   3. blogContext fields (description, date, author, tags, slug, draft, coverImage)
+ *
+ * Field-name mapping: blogContext keys are renamed via `site.frontmatter_field_map`
+ * before emit (e.g. `date` → `publishedDate` for Astro sites).
+ *
+ * Top-level openwriter metadata (status, enrichmentStale, tags-as-content-type,
+ * etc.) is NEVER passed through. Frontmatter is built ONLY from blogContext +
+ * defaults — this is the design contract from server/blog-routes.ts.
+ */
+export declare function buildFrontmatter(title: string, blogCtx: Record<string, any>, site: BlogSite, coverImagePath?: string): string;
 export declare function blogTools(): PluginMcpTool[];

package/dist/plugins/github/dist/blog-tools.js CHANGED Viewed

@@ -6,7 +6,7 @@
  */
 import { execFile } from 'child_process';
 import { existsSync, mkdirSync, readFileSync, copyFileSync, writeFileSync, readdirSync, statSync, rmSync } from 'fs';
-import { join, extname, dirname } from 'path';
+import { join, extname, dirname, basename } from 'path';
 import { randomUUID } from 'crypto';
 import { homedir } from 'os';
 import { getServerModules, listBlogSites, writeBlogSites, } from './helpers.js';
@@ -31,6 +31,33 @@ async function ghAuthOk(cwd) {
         return false;
     }
 }
+/**
+ * Last-resort site-URL detection via the GitHub Pages API. `inferSiteUrl`
+ * only reads files committed to the repo (CNAME, wrangler route); this
+ * catches GitHub Pages sites whose served URL — custom domain or the
+ * `<owner>.github.io/<repo>` default — lives in Pages settings, not a file.
+ * Returns the canonical served base URL (trailing slash stripped), or
+ * undefined when Pages is not enabled / not accessible. Credential-free
+ * (rides the existing `gh auth`); other hosts (Cloudflare Pages, Vercel,
+ * Netlify) configure the domain in their dashboard and can't be derived
+ * here — those rely on the user supplying site_url.
+ */
+async function inferSiteUrlFromGitHubPages(owner, repo, cwd) {
+    try {
+        const out = await exec('gh', ['api', `repos/${owner}/${repo}/pages`, '--jq', '.html_url'], cwd);
+        const url = out.split('\n')[0].trim();
+        if (/^https?:\/\//i.test(url))
+            return url.replace(/\/+$/, '');
+    }
+    catch { /* Pages not enabled, or no access — fall through */ }
+    return undefined;
+}
+// Shared hint surfaced when site_url couldn't be determined, so the agent
+// knows to ask the user rather than silently shipping posts with no live link.
+const SITE_URL_HINT = 'Could not auto-detect the public site URL (no CNAME, wrangler route, or GitHub Pages config — ' +
+    'common for Cloudflare Pages / Vercel / Netlify sites whose domain lives in the host dashboard). ' +
+    'Ask the user for the public base URL (e.g. https://example.com) and set it via site_url. ' +
+    'Without it, published posts get no clickable "View Post" link (only the commit/file).';
 function slugify(s) {
     return s.toLowerCase().replace(/['"]/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 80);
 }
@@ -207,6 +234,121 @@ function inferFrontmatterShape(rawSamples) {
     }
     return { defaults, field_map, schema: schemaOrder };
 }
+// ---- Image-contract inference (inspect_blog_repo) ----
+// adr: adr/blog-image-contract.md
+const IMAGE_FIELD_CANDIDATES = [
+    'image', 'coverImage', 'cover', 'ogImage', 'heroImage', 'featuredImage', 'thumbnail', 'banner',
+];
+const IMAGE_VALUE_RE = /\.(png|jpe?g|webp|gif|avif|svg)\b/i;
+function unquoteScalar(s) {
+    const m = s.match(/^["'](.*)["']$/);
+    return m ? m[1] : s;
+}
+/**
+ * Pick the frontmatter key that holds the post's cover image. Prefers the
+ * conventional names in order; the value must look like a local image path
+ * (carries an image extension). Falls back to any field whose value does.
+ */
+function pickImageField(fm) {
+    for (const k of IMAGE_FIELD_CANDIDATES) {
+        const raw = fm[k];
+        if (!raw || raw === '<multiline>')
+            continue;
+        const v = unquoteScalar(raw);
+        if (IMAGE_VALUE_RE.test(v))
+            return { key: k, value: v };
+    }
+    for (const [k, raw] of Object.entries(fm)) {
+        if (raw === '<multiline>')
+            continue;
+        const v = unquoteScalar(raw);
+        if (IMAGE_VALUE_RE.test(v))
+            return { key: k, value: v };
+    }
+    return null;
+}
+/**
+ * Derive the per-site image contract from sampled posts:
+ *  - `image_field`        — which frontmatter key holds the cover
+ *  - `image_path_style`   — do values carry a leading slash?
+ *  - `image_public_prefix`— the dominant directory the images live under
+ *                           (relative, no leading slash)
+ *  - `image_naming`       — `og-{slug}` vs `{slug}` filename convention
+ *                           (detected by the dominant basename shape)
+ * Conservative: only the dominant local-path field is analyzed; full URLs
+ * are ignored. Anything not confidently detected is left undefined so
+ * post_to_blog falls back to its documented defaults.
+ */
+export function inferImageConventions(samples) {
+    const hits = [];
+    for (const s of samples) {
+        const pick = pickImageField(s.fm);
+        if (pick)
+            hits.push({ ...pick, slug: s.slug });
+    }
+    if (hits.length === 0)
+        return {};
+    // Dominant cover field name
+    const fieldCounts = new Map();
+    for (const h of hits)
+        fieldCounts.set(h.key, (fieldCounts.get(h.key) || 0) + 1);
+    const image_field = [...fieldCounts.entries()].sort((a, b) => b[1] - a[1])[0][0];
+    // Only local paths of the dominant field tell us about the path contract
+    const local = hits.filter((h) => h.key === image_field && !/^https?:\/\//i.test(h.value) && !h.value.startsWith('//'));
+    if (local.length === 0)
+        return { image_field };
+    // Path style: majority leading-slash ⇒ absolute
+    const abs = local.filter((h) => h.value.startsWith('/')).length;
+    const image_path_style = abs > local.length / 2 ? 'absolute' : 'relative';
+    // Public prefix: dominant directory portion (no leading/trailing slash)
+    const dirCounts = new Map();
+    for (const h of local) {
+        const noSlash = h.value.replace(/^\/+/, '');
+        const dir = noSlash.includes('/') ? noSlash.slice(0, noSlash.lastIndexOf('/')) : '';
+        dirCounts.set(dir, (dirCounts.get(dir) || 0) + 1);
+    }
+    const topDir = [...dirCounts.entries()].sort((a, b) => b[1] - a[1])[0][0];
+    const image_public_prefix = topDir || undefined;
+    // Naming convention by dominant basename shape + extension
+    let ogCount = 0;
+    let slugCount = 0;
+    const extCounts = new Map();
+    for (const h of local) {
+        const base = h.value.replace(/^.*\//, '');
+        const ext = (base.match(/\.([a-z0-9]+)$/i)?.[1] || 'png').toLowerCase();
+        extCounts.set(ext, (extCounts.get(ext) || 0) + 1);
+        const stem = base.replace(/\.[a-z0-9]+$/i, '');
+        if (stem === h.slug)
+            slugCount++;
+        else if (stem.startsWith('og-'))
+            ogCount++;
+    }
+    const dominantExt = [...extCounts.entries()].sort((a, b) => b[1] - a[1])[0][0];
+    let image_naming;
+    if (slugCount > local.length / 2)
+        image_naming = `{slug}.${dominantExt}`;
+    else if (ogCount > local.length / 2)
+        image_naming = `og-{slug}.${dominantExt}`;
+    // else: undefined ⇒ post_to_blog default (og-{slug}.{ext})
+    return { image_field, image_path_style, image_public_prefix, image_naming };
+}
+/**
+ * Map an inferred (relative) public image prefix to the on-disk image_dir
+ * for the framework's static-asset root.
+ */
+function imageDirForFramework(fw, prefix) {
+    switch (fw) {
+        case 'astro':
+        case 'next':
+            return `public/${prefix}`;
+        case 'hugo':
+            return `static/${prefix}`;
+        case 'jekyll':
+            return prefix; // served from repo root
+        default:
+            return `public/${prefix}`;
+    }
+}
 /**
  * Detect the site's public URL from common static-host conventions:
  *  - `CNAME` at repo root or `public/CNAME` (GitHub Pages / Cloudflare Pages / Netlify)
@@ -320,6 +462,49 @@ function formatDate(v) {
     const m = v.match(/^(\d{4}-\d{2}-\d{2})/);
     return m ? m[1] : v;
 }
+// ---- Per-site image contract (path style + cover naming) ----
+// adr: adr/blog-image-contract.md
+//
+// The image reference is a PER-SITE CONTRACT, not a global assumption. Two
+// dimensions, both stored on BlogSite and inferred by inspect_blog_repo:
+//   1. path style — does the value carry a leading slash, or does the site's
+//      template prepend one? (`image_path_style`)
+//   2. cover filename — deterministic `og-{slug}.{ext}`, never the raw
+//      `/_images/` name, so republish is idempotent and never orphans.
+//        (`image_naming`)
+// Absent keys ⇒ legacy behavior ("absolute", raw name) so already-correct
+// sites never regress.
+/** Site's effective path style. Absent ⇒ legacy "absolute". */
+export function pathStyleOf(site) {
+    return site.image_path_style === 'relative' ? 'relative' : 'absolute';
+}
+/**
+ * Public reference for one image file under the site's prefix, honoring the
+ * site's path style. The prefix is normalized (leading + trailing slashes
+ * stripped) so storage is style-agnostic — `style` alone decides the leading
+ * slash, which makes the contract unambiguous regardless of how the prefix
+ * was saved (`/images/og` vs `images/og` both behave identically).
+ *   relative → "images/og/x.png"   absolute → "/images/og/x.png"
+ */
+export function imageRef(publicPrefix, file, style) {
+    const seg = (publicPrefix || '').replace(/^\/+/, '').replace(/\/+$/, '');
+    const rel = seg ? `${seg}/${file}` : file;
+    return style === 'absolute' ? `/${rel}` : rel;
+}
+/**
+ * Resolve the deterministic cover filename from the site's naming template.
+ *   `{slug}` → post slug
+ *   `{ext}`  → source extension, no dot (preserved from the original)
+ * A template carrying a literal extension and no `{ext}` placeholder
+ * (e.g. `og-{slug}.png`) is respected as authored. Absent template ⇒
+ * `og-{slug}.{ext}`.
+ */
+export function coverFilename(template, slug, sourceExt) {
+    const ext = sourceExt.replace(/^\.+/, '');
+    return (template || 'og-{slug}.{ext}')
+        .replace(/\{slug\}/g, slug)
+        .replace(/\{ext\}/g, ext);
+}
 /**
  * Build the YAML frontmatter from blogContext + site defaults.
  *
@@ -335,7 +520,7 @@ function formatDate(v) {
  * etc.) is NEVER passed through. Frontmatter is built ONLY from blogContext +
  * defaults — this is the design contract from server/blog-routes.ts.
  */
-function buildFrontmatter(title, blogCtx, site, coverImagePath) {
+export function buildFrontmatter(title, blogCtx, site, coverImagePath) {
     const fm = {};
     const map = site.frontmatter_field_map || {};
     // 1. Site defaults (lowest priority — overridable below)
@@ -463,33 +648,60 @@ export function blogTools() {
                     return (detected ? rel.startsWith(detected + '/') : true) && /\.(md|mdx)$/i.test(rel);
                 })
                     .slice(0, 10);
-                const rawSamples = [];
+                const sampleData = [];
                 for (const f of sampleFiles) {
                     try {
-                        rawSamples.push(parseYamlFrontmatter(readFileSync(f, 'utf-8')));
+                        const fm = parseYamlFrontmatter(readFileSync(f, 'utf-8'));
+                        const slug = basename(f).replace(/\.(md|mdx)$/i, '');
+                        sampleData.push({ fm, slug });
                     }
                     catch { /* skip */ }
                 }
+                const rawSamples = sampleData.map((s) => s.fm);
                 const samplesAfterFilter = rawSamples.filter((s) => !looksLikeOpenwriterLeak(s));
                 const samplesSkipped = rawSamples.length - samplesAfterFilter.length;
                 const shape = inferFrontmatterShape(rawSamples);
+                // Per-site image contract — inferred from real posts (path style, the
+                // directory images live under, og-{slug} vs {slug} naming, and which
+                // frontmatter field holds the cover). Leak samples excluded so the
+                // old plugin's emit doesn't poison detection. adr: adr/blog-image-contract.md
+                const conv = inferImageConventions(sampleData.filter((s) => !looksLikeOpenwriterLeak(s.fm)));
+                const imagePublicPrefix = conv.image_public_prefix ?? defaults.image_public_prefix;
+                const imageDir = conv.image_public_prefix
+                    ? imageDirForFramework(framework, conv.image_public_prefix)
+                    : defaults.image_dir;
+                const imagePathStyle = conv.image_path_style ?? 'absolute';
+                const imageNaming = conv.image_naming ?? 'og-{slug}.{ext}';
+                // Cover field-name mapping (e.g. site uses `image:` not `coverImage:`)
+                const fieldMap = { ...shape.field_map };
+                if (conv.image_field && conv.image_field !== 'coverImage') {
+                    fieldMap.coverImage = conv.image_field;
+                }
                 const confidence = framework !== 'unknown' && detected ? 'high'
                     : detected ? 'medium'
                         : 'low';
-                const siteUrl = inferSiteUrl(cloneDir);
+                // site_url: prefer files committed to the repo (CNAME / wrangler route),
+                // then fall back to the GitHub Pages API for GH-hosted sites whose served
+                // URL lives in Pages settings rather than a committed file.
+                const siteUrl = inferSiteUrl(cloneDir) || await inferSiteUrlFromGitHubPages(owner, repo, cacheRoot);
                 return {
                     owner,
                     repo,
                     framework,
                     content_dir: defaults.content_dir,
-                    image_dir: defaults.image_dir,
-                    image_public_prefix: defaults.image_public_prefix,
+                    image_dir: imageDir,
+                    image_public_prefix: imagePublicPrefix,
+                    image_path_style: imagePathStyle,
+                    image_naming: imageNaming,
                     frontmatter_schema: shape.schema,
                     frontmatter_defaults: shape.defaults,
-                    frontmatter_field_map: shape.field_map,
+                    frontmatter_field_map: fieldMap,
                     // Always propose a pattern even when site_url is unknown so the user can fill in the URL
                     site_url: siteUrl,
                     blog_url_pattern: '/blog/{slug}/',
+                    // When site_url couldn't be derived, tell the agent to ask the user —
+                    // otherwise it ships posts with no live "View Post" link, silently.
+                    ...(siteUrl ? {} : { needs_site_url: true, site_url_hint: SITE_URL_HINT }),
                     samples_analyzed: samplesAfterFilter.length,
                     samples_skipped_openwriter_leak: samplesSkipped,
                     markdown_files_found: mdBest?.count ?? 0,
@@ -509,7 +721,9 @@ export function blogTools() {
                     branch: { type: 'string', description: 'Branch to push to (default: main)' },
                     content_dir: { type: 'string', description: 'Directory where post .md files live (e.g. "src/content/blog")' },
                     image_dir: { type: 'string', description: 'Directory where image files write (e.g. "public/blog-images")' },
-                    image_public_prefix: { type: 'string', description: 'URL prefix for images in markdown (e.g. "/blog-images")' },
+                    image_public_prefix: { type: 'string', description: 'Directory prefix images live under (e.g. "images/og" or "/blog-images"). The leading slash is governed by image_path_style, not by how this is stored.' },
+                    image_path_style: { type: 'string', enum: ['relative', 'absolute'], description: 'How image paths are written: "relative" = no leading slash (`images/og/x.png`; the template prepends one), "absolute" = leading slash (`/images/og/x.png`; used verbatim). inspect_blog_repo infers this from existing posts. Default: "absolute" (legacy).' },
+                    image_naming: { type: 'string', description: 'Cover filename template with `{slug}` + `{ext}` placeholders. Default "og-{slug}.{ext}". Deterministic: same doc+slug ⇒ same filename every republish (no orphaned covers).' },
                     framework: { type: 'string', enum: ['astro', 'next', 'jekyll', 'hugo', 'unknown'], description: 'Site framework' },
                     frontmatter_defaults: {
                         type: 'object',
@@ -526,7 +740,7 @@ export function blogTools() {
                     },
                     site_url: {
                         type: 'string',
-                        description: 'Public base URL of the site (e.g. "https://example.com"). Used to construct the live URL surfaced after publish. inspect_blog_repo proposes this from CNAME / wrangler.toml when found.',
+                        description: 'Public base URL of the site (e.g. "https://example.com"). Used to construct the live "View Post" URL surfaced after publish. inspect_blog_repo proposes this from CNAME / wrangler.toml / the GitHub Pages API when found; for Cloudflare Pages / Vercel / Netlify (domain configured in the host dashboard) it can\'t be auto-detected — ask the user and pass it here. If omitted, the response returns needs_site_url so you know to follow up; backfill later with edit_blog_site.',
                     },
                     blog_url_pattern: {
                         type: 'string',
@@ -553,6 +767,12 @@ export function blogTools() {
                 if (params.frontmatter_field_map && typeof params.frontmatter_field_map === 'object') {
                     site.frontmatter_field_map = params.frontmatter_field_map;
                 }
+                if (params.image_path_style === 'relative' || params.image_path_style === 'absolute') {
+                    site.image_path_style = params.image_path_style;
+                }
+                if (typeof params.image_naming === 'string' && params.image_naming.trim()) {
+                    site.image_naming = params.image_naming.trim();
+                }
                 if (Array.isArray(params.frontmatter_schema)) {
                     site.frontmatter_schema = params.frontmatter_schema.map(String);
                 }
@@ -565,7 +785,12 @@ export function blogTools() {
                 const sites = await listBlogSites();
                 sites.push(site);
                 await writeBlogSites(sites);
-                return { success: true, site };
+                return {
+                    success: true,
+                    site,
+                    // No site_url ⇒ no live link on publish. Tell the agent to follow up.
+                    ...(site.site_url ? {} : { needs_site_url: true, site_url_hint: SITE_URL_HINT }),
+                };
             },
         },
         {
@@ -597,6 +822,68 @@ export function blogTools() {
                 return { success: true, removed: id };
             },
         },
+        {
+            name: 'edit_blog_site',
+            description: 'Update fields on an already-registered blog site by id. Only the fields you pass change; everything else is left intact. The common use is backfilling site_url / blog_url_pattern after registration so published posts get a live "View Post" link (e.g. for Cloudflare Pages / Vercel / Netlify sites where the domain couldn\'t be auto-detected).',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    id: { type: 'string', description: 'Blog site id (from list_blog_sites)' },
+                    label: { type: 'string', description: 'User-facing name' },
+                    branch: { type: 'string', description: 'Branch to push to' },
+                    content_dir: { type: 'string', description: 'Directory where post .md files live' },
+                    image_dir: { type: 'string', description: 'Directory where image files write' },
+                    image_public_prefix: { type: 'string', description: 'Directory prefix images live under' },
+                    image_path_style: { type: 'string', enum: ['relative', 'absolute'], description: 'How image paths are written' },
+                    image_naming: { type: 'string', description: 'Cover filename template with `{slug}` + `{ext}`' },
+                    framework: { type: 'string', enum: ['astro', 'next', 'jekyll', 'hugo', 'unknown'], description: 'Site framework' },
+                    frontmatter_defaults: { type: 'object', description: 'Constants applied to every post\'s frontmatter' },
+                    frontmatter_field_map: { type: 'object', description: 'Rename map: openwriter blogContext key → site frontmatter key' },
+                    frontmatter_schema: { type: 'array', items: { type: 'string' }, description: 'List of frontmatter keys the site uses' },
+                    site_url: { type: 'string', description: 'Public base URL (e.g. "https://example.com"). Pass an empty string to clear it.' },
+                    blog_url_pattern: { type: 'string', description: 'URL path pattern with `{slug}` placeholder (e.g. "/blog/{slug}/").' },
+                },
+                required: ['id'],
+            },
+            handler: async (params) => {
+                const id = String(params.id);
+                const sites = await listBlogSites();
+                const site = sites.find(s => s.id === id);
+                if (!site)
+                    return { error: `No blog site with id ${id}` };
+                // Plain string fields — set when a non-empty string is provided.
+                for (const key of ['label', 'branch', 'content_dir', 'image_dir', 'image_public_prefix', 'image_naming', 'blog_url_pattern']) {
+                    if (typeof params[key] === 'string' && params[key].trim()) {
+                        site[key] = params[key].trim();
+                    }
+                }
+                // site_url: trim + strip trailing slash; empty string clears it.
+                if (typeof params.site_url === 'string') {
+                    const v = params.site_url.trim().replace(/\/+$/, '');
+                    if (v)
+                        site.site_url = v;
+                    else
+                        delete site.site_url;
+                }
+                if (params.image_path_style === 'relative' || params.image_path_style === 'absolute') {
+                    site.image_path_style = params.image_path_style;
+                }
+                if (params.framework && ['astro', 'next', 'jekyll', 'hugo', 'unknown'].includes(String(params.framework))) {
+                    site.framework = params.framework;
+                }
+                if (params.frontmatter_defaults && typeof params.frontmatter_defaults === 'object') {
+                    site.frontmatter_defaults = params.frontmatter_defaults;
+                }
+                if (params.frontmatter_field_map && typeof params.frontmatter_field_map === 'object') {
+                    site.frontmatter_field_map = params.frontmatter_field_map;
+                }
+                if (Array.isArray(params.frontmatter_schema)) {
+                    site.frontmatter_schema = params.frontmatter_schema.map(String);
+                }
+                await writeBlogSites(sites);
+                return { success: true, site };
+            },
+        },
         {
             name: 'post_to_blog',
             description: 'Publish the active OpenWriter document to a registered GitHub blog site via local git ops (clone-or-pull, write file + images, commit, push). Auth uses your existing `gh auth login`.',
@@ -685,24 +972,35 @@ export function blogTools() {
                 if (!slug)
                     return { error: 'Could not derive a slug from the title.' };
                 // Rewrite inline image refs in body, collect filenames
-                const imgPrefix = site.image_public_prefix.replace(/\/+$/, '');
+                // Per-site image contract: path style governs the leading slash on
+                // every emitted reference (cover + inline body). adr: adr/blog-image-contract.md
+                const style = pathStyleOf(site);
+                // Inline body images keep their source (hash) filenames — only the
+                // path style is normalized. Deterministic slug naming is scoped to the
+                // COVER for now (inline naming is a noted follow-up in the ADR).
                 const imageRefs = new Set();
                 const bodyRewritten = bodyMd.replace(/\/_images\/([^\s)"'<>]+)/g, (_m, fn) => {
                     imageRefs.add(fn);
-                    return `${imgPrefix}/${fn}`;
+                    return imageRef(site.image_public_prefix, fn, style);
                 });
-                // Handle cover image from blogContext
+                // Cover image from blogContext → deterministic `og-{slug}.{ext}` name.
+                // Same doc + slug ⇒ same filename every republish (idempotent
+                // overwrite, no orphaned cover). Source extension is preserved.
                 let coverImagePath;
+                let coverSrcFile;
+                let coverDestFile;
                 if (typeof blogCtx.coverImage === 'string' && blogCtx.coverImage) {
-                    const coverFile = blogCtx.coverImage.replace(/^\/_images\//, '');
-                    imageRefs.add(coverFile);
-                    coverImagePath = `${imgPrefix}/${coverFile}`;
+                    coverSrcFile = blogCtx.coverImage.replace(/^\/_images\//, '');
+                    const ext = extname(coverSrcFile) || '.png';
+                    coverDestFile = coverFilename(site.image_naming, slug, ext);
+                    coverImagePath = imageRef(site.image_public_prefix, coverDestFile, style);
                 }
                 // Copy images
                 const dataDir = srv.getDataDir();
                 const imageDirAbs = join(clonePath, site.image_dir);
                 mkdirSync(imageDirAbs, { recursive: true });
                 let imagesCopied = 0;
+                // Inline images — copied under their source filename
                 for (const fn of imageRefs) {
                     const src = join(dataDir, '_images', fn);
                     if (!existsSync(src))
@@ -712,6 +1010,16 @@ export function blogTools() {
                     copyFileSync(src, dst);
                     imagesCopied++;
                 }
+                // Cover — copied under the deterministic slug-based name
+                if (coverSrcFile && coverDestFile) {
+                    const src = join(dataDir, '_images', coverSrcFile);
+                    if (existsSync(src)) {
+                        const dst = join(imageDirAbs, coverDestFile);
+                        mkdirSync(dirname(dst), { recursive: true });
+                        copyFileSync(src, dst);
+                        imagesCopied++;
+                    }
+                }
                 // Write the post file
                 const frontmatter = buildFrontmatter(title, blogCtx, site, coverImagePath);
                 const postRel = join(site.content_dir, `${slug}.md`);
@@ -771,6 +1079,15 @@ export function blogTools() {
                     // Same convention mcp.ts:1112 uses for active-doc metadata writes.
                     srv.bumpDocVersion();
                     srv.save();
+                    // Notify every connected client so the file-tree "published" ✓ + the
+                    // "Republish to Blog" context-menu label + the compose-view "Published"
+                    // pill flip live, with no manual reload. metadata-changed updates the
+                    // active doc's compose view; documents-changed re-reads /api/documents
+                    // (where blogContext.lastPublish.publishedUrl → postedUrl drives the
+                    // file tree). Mirrors the broadcast-after-setMetadata convention the
+                    // core MCP tools follow. adr: adr/plugin-metadata-broadcast.md
+                    srv.broadcastMetadataChanged(srv.getMetadata());
+                    srv.broadcastDocumentsChanged();
                 }
                 catch (err) {
                     writebackWarning = `Published successfully, but failed to mark doc as sent: ${err.message}`;
@@ -780,6 +1097,9 @@ export function blogTools() {
                     file: postRel.replace(/\\/g, '/'),
                     commit: shortHash,
                     images_committed: noChanges ? 0 : imagesCopied,
+                    // Transparency: the exact cover path written to frontmatter + the
+                    // filename it shipped as, so the agent/user sees what landed.
+                    ...(coverImagePath ? { image: coverImagePath, cover_file: coverDestFile } : {}),
                     live_url: liveUrl,
                     message: noChanges
                         ? 'No changes — file already up to date. Doc marked as sent.'