Word Add-in

Repository layout

Lives at ~/projects/hugo-folder/hugo-worker/office-addins/word/. Self-contained — no shared library, no workspace. Patterned on the Gustav DMS Word add-in but inlined and re-skinned with the same design tokens.

office-addins/word/
├── manifest.xml          # Office add-in manifest (sideload this)
├── package.json
├── tsconfig.json
├── webpack.config.js     # HTTPS dev server on :3000, ts-loader, style-loader
├── README.md             # Build & sideload instructions
├── .gitignore
├── assets/               # Ribbon icons 16/32/80
│   ├── icon-16.png
│   ├── icon-32.png
│   └── icon-80.png
└── src/
    ├── taskpane.html     # Tab shell, Office.js script tag, filter pill grid
    ├── taskpane.css      # Imports ./styles/base.css; Hugo-specific overrides
    ├── taskpane.ts       # Bootstrap, tabs, clauses tab, filter pills, chat tab
    ├── api.ts            # fetch wrappers for Hugo API (facets, search, chat)
    ├── types.ts          # ClauseFilters, FacetRow, ClauseSearchHit, …
    └── styles/
        └── base.css      # Design tokens (sky blue, warm grey, 6px radii)

Bundle target: dist/taskpane.bundle.js (~40 KB minified). Production assets are committed to hugo-worker/public/addin/word/ and served by the main Hugo Worker via [assets] directory = "./public".

Local development

Prerequisites (one-time)

cd ~/projects/hugo-folder/hugo-worker/office-addins/word
npm install
npx office-addin-dev-certs install   # trusts the local HTTPS cert

Run two terminals

# Terminal 1 — Hugo backend (HTTPS so the add-in can fetch it without
# mixed-content errors).
cd ~/projects/hugo-folder/hugo-worker
npx wrangler dev --local --local-protocol https --port 8788

# Terminal 2 — add-in dev server (HTTPS on :3000, required by Office.js)
cd ~/projects/hugo-folder/hugo-worker/office-addins/word
npm run dev

Test in a plain browser (no Word required)

Useful for fast iteration on this VPS, where Word isn't available:

https://localhost:3000/taskpane.html?api=https://localhost:8788

Accept both self-signed certs once. The add-in shows a BROWSER badge and disables Word-specific actions (Insert shows a toast instead of throwing).

Build & deploy to prod

cd ~/projects/hugo-folder/hugo-worker/office-addins/word
npm run build                                      # webpack production bundle
cp -r dist/* ../../public/addin/word/              # copy into Hugo's static assets
cp manifest.xml ../../public/addin/word/manifest.xml
cd ../..
npx wrangler deploy                                # ships everything in one go

Sideloading on Mac / Windows / Web

The deployed manifest at https://hugo.nordiclawfirm.com/addin/word/manifest.xml already points at the production assets. To sideload elsewhere edit manifest.xml first.

mkdir -p ~/Library/Containers/com.microsoft.Word/Data/Documents/wef
curl -o ~/Library/Containers/com.microsoft.Word/Data/Documents/wef/hugo-clauses.xml \
  https://hugo.nordiclawfirm.com/addin/word/manifest.xml

Production hosting model

The add-in is served as static assets from the production Hugo Worker, mirroring how Gustav hosts its Office add-in. Two pieces:

1. Static asset binding

# hugo-worker/wrangler.toml
[assets]
directory = "./public"
html_handling = "none"   # keep .html literal so Office manifest URLs don't 307

2. CF Access path bypass

Hugo's CF Access app gates the entire hugo.nordiclawfirm.com origin. A second Access app with a more-specific scope hugo.nordiclawfirm.com/addin carries a single bypass: everyone policy at precedence 1, so the add-in's manifest, taskpane HTML, and bundle are reachable from any sideloaded Word session without an Access challenge:

Why this model

• One redeploy ships add-in updates to every user instantly. No per-machine reinstall.
• Manifest URLs are stable and HTTPS — Word for Mac, Windows, and Online all accept them.
• No tunnel, no localhost certs, no per-user setup beyond a one-time manifest sideload.
• Same auth surface as the rest of Hugo — no separate identity for the add-in.

Filter dimensions

The Clauses tab supports 8 combinable filter dimensions plus a free-text search. Each dimension is OR within itself (multi-select within one dimension), and dimensions are AND across. The whole filter spec is sent to GET /api/clauses/search as repeated query params (e.g. ?clause_name_id=cn_mfn&clause_name_id=cn_erisa&investor_category_id=ic_swf).

Output modes

Two extra query params switch the response shape:

• ?count_only=1 — returns {"count": N} instead of rows. Use for "how many" questions.
• ?group_by=<dim> — returns {"results": [{key, label, count}, …]} sorted by count desc. Allowed dims: clause_name_id, clause_group_id, fund_id, fund_category_id, gp_name, vintage_year, lifecycle_status, source.

API endpoint reference

Chat dispatcher

The chat tab posts the conversation history to POST /api/chat on every turn. The handler runs a 3-pass dispatch regardless of whether the live model is wired:

Why two passes (and not Anthropic tool_use)

Heimdall is OpenAI-compatible text-only — the underlying claude -p CLI doesn't expose tool_use through the proxy. So instead of one round-trip with native tool calls, we do JSON intent → execute → synthesize. Both passes go through the same runChat() helper in src/lib/ai.ts; both are gated behind the same env flag.

Response shape

{
  "assistant": "Across our 4 funds with 2024 vintage, the modal SFDR clause is Article 8 (3 funds), with Article 8 Plus appearing in 1 fund (cls_cvx9_sfdr_v1)…",
  "trace": {
    "intent": {
      "tool": "aggregate_clauses",
      "filters": { "clause_name_id": ["cln_sfdr"], "vintage_year": [2024] },
      "group_by": "clause_group_id",
      "max_results": 25,
      "summary_focus": "What is market standard for SFDR across our 2024 closes?"
    },
    "tool_result": { "kind": "aggregate", "rows": 1 }
  },
  "latency_ms": 64
}

The taskpane renders the trace as a small breadcrumb above the assistant bubble (e.g. 🔧 aggregate_clauses · clause_name_id=cln_sfdr · vintage_year=2024 · group_by=clause_group_id → 1 rows) so users can see exactly which dispatch the router chose.

Enabling the live model

# In hugo-worker/wrangler.toml [vars] section
CHAT_LIVE = "1"

# Or via secret if you want to flip it without a redeploy:
npx wrangler secret put CHAT_LIVE   # value: 1

Until that's set, every chat turn returns the offline-templated answer. The chat tab is fully functional in offline mode — you can verify dispatch correctness, look at intent traces, and exercise every tool path without any AI traffic.

Tool registry

Five tools are exposed to the chat router. Each is dispatched by the tool field of the intent JSON. Filters apply to all tools that accept them; arguments are resolved client-side (in the Worker) before reaching D1.

Chat context endpoint

The dispatcher's system prompt is built fresh on every request from /api/chat/context, which returns:

{
  "schema_version": "1.0.0",
  "generated_at": "2026-04-12T22:47:11.000Z",
  "description": "Hugo clause-corpus chat context. …",
  "dimensions": [
    { "param": "q",                    "type": "string",   "description": "…" },
    { "param": "fund_id",              "type": "string[]", "description": "…" },
    { "param": "fund_category_id",     "type": "string[]", "description": "…" },
    { "param": "gp_name",              "type": "string[]", "description": "…" },
    { "param": "vintage_year",         "type": "number[]", "description": "…" },
    { "param": "clause_name_id",       "type": "string[]", "description": "…" },
    { "param": "investor_id",          "type": "string[]", "description": "…" },
    { "param": "investor_category_id", "type": "string[]", "description": "…" },
    { "param": "lp_country_code",      "type": "string[]", "description": "…" },
    { "param": "lifecycle_status",     "type": "string[]", "description": "…" },
    { "param": "source",               "type": "string[]", "description": "…" },
    { "param": "count_only",           "type": "0|1",      "description": "…" },
    { "param": "group_by",             "type": "enum",     "description": "…" }
  ],
  "enums": {
    "clause_names":         [ {id, name}, … ],
    "investor_categories":  [ {id, name}, … ],
    "fund_categories":      [ {id, name}, … ],
    "gps":                  [ {id, name}, … ],
    "lp_countries":         [ {id, name}, … ]
  },
  "accessible_funds": [ {id, name, gp_name, vintage_year}, … ],
  "rules": [
    "Only answer using the tool results. …",
    "Always cite clause IDs and fund IDs in your answer …",
    "For 'how many' / 'what proportion' questions, prefer count_only or group_by …",
    "Resolve plain-English entity names (e.g. 'sovereign wealth', 'German LPs', 'Northstar VIII') to IDs …"
  ]
}

The full preamble is ~1.5–2k tokens once enums are inlined. Cached client-side per session in the production model path. The same payload is also stitched into the offline matcher's resolution tables.

Extending: cookbook

Add a new filter dimension

1. Backend (src/index.tsx, inside clauseSearchHandler):
   • Read the param: const fooIds = all('foo_id');
   • Add a WHERE clause with parameterized placeholders: where.push(`c.foo IN (${fooIds.map(() => '?').join(',')})`); binds.push(...fooIds);
   • If the filter requires joins outside the main FROM (e.g. through clause_assignments), use an EXISTS (…) subquery so you don't multiply rows.
2. Backend (src/index.tsx, /api/chat/context): add a new entry to the dimensions array with a plain-English description.
3. Backend (offline matcher inside /api/chat): add a resolver block that maps user words to the filter values. Use word-boundary regex matching, not substring.
4. Frontend types (office-addins/word/src/types.ts): add the field to ClauseFilters.
5. Frontend api (src/api.ts): add the field to the dims list inside filtersToParams.
6. Frontend state (src/taskpane.ts): add the field to the FilterDim union, the state.filters initializer, the labels map, DIM_DISPLAY, DIM_ORDER, and either STATIC_OPTIONS (for hardcoded enums) or getDimOptions (for facet-driven ones).
7. Frontend HTML — nothing to add: the pill grid is built dynamically from DIM_ORDER.
8. Frontend bootstrap (bootstrapClauses): if the new dimension needs a facet endpoint, add the fetch + populate the label map.
9. Backend facet endpoint (optional): add GET /api/<dim> returning {results: [{id, name, count}]}.

Add a new tool

1. In src/index.tsx: add a new entry to the ChatIntent['tool'] union and a new case branch in executeChatTool.
2. If the tool needs a new SQL shape, write a fresh internal helper rather than overloading clauseSearchHandler — the latter is the source of truth for the filter/group/count semantics, don't bend it.
3. Add the tool's name and description to the buildIntentSystemPrompt "AVAILABLE TOOLS" section so the live router knows about it.
4. Add a case to the offline extractIntentOffline matcher's tool-selection heuristic so the offline path can route to it on a recognizable phrase.
5. Add a case to synthesizeOffline so the templated synthesis can render the tool's result shape.
6. Document the tool here (in this page). Cookbook lives in code; reference lives in docs.

Wire the live model (Heimdall)

1. Set CHAT_LIVE = "1" in hugo-worker/wrangler.toml [vars] section.
2. Verify AI_GATEWAY_ID and CHAT_MODEL are set (already in production: hugo-gateway + heimdall/sonnet).
3. If Heimdall has bearer auth enabled: npx wrangler secret put HEIMDALL_API_TOKEN.
4. Redeploy. The next chat request will route through Heimdall instead of the offline matcher.
5. Watch npx wrangler tail hugo for any 5xx from the gateway URL — common causes are gateway misconfig (custom-heimdall slug missing) or Heimdall systemd unit being down on Odin.

Cost-safety guarantees

• No wrangler.toml in office-addins/word/ → no CF bindings can leak in.
• No imports from hugo-worker/src/lib/ai*, no Workers AI / Vectorize / Anthropic / AI Gateway references anywhere in the add-in's src/.
• The Clauses tab makes only D1 reads via the existing /api/clauses/search handler — zero AI in the hot path.
• The Chat tab runs the offline keyword matcher + templated synthesis until CHAT_LIVE=1. No runChat() call is reachable in the default config.
• Heimdall is the eventual provider (Axel's Max subscription, fixed monthly cost) — even when wired, marginal per-message cost is zero.

Known limitations

1. Offline matcher is approximate. Word-boundary regex matching against enum names + initials handles the canonical question shapes, but ambiguous tokens (e.g. "sovereign" appearing in both an investor category and a clause type) can over-match. The model path resolves these correctly with full context.
2. Single-fund clause search is per-fund. The legacy /api/funds/:fundId/clauses/search stays for backward compatibility; new code should use the cross-fund /api/clauses/search.
3. Plain-text insertion only. Clauses are TEXT in D1; rich formatting would need insertOoxml + a structured storage shape.
4. No automated E2E. Playwright cannot drive the Word ribbon. Smoke testing is browser-based against /addin/word/taskpane.html with extraHTTPHeaders for the CF Access service token; manual sideload is the only real Word verification.

Related

• Word Add-in — Sources — annotated bibliography of Microsoft Learn / OfficeDev / MVP best-practice references (28 sections, ~120 verified links)
• API Reference — every JSON endpoint Hugo exposes
• Clause Export API — bulk export for offline analysis
• Authentication — how the cookie + CF Access fallback works