Skip to content

docs(site): replace the chat footer with a risk notice and add follow-ups - #1144

Merged
Birfy merged 2 commits into
mainfrom
agent/site-chat-footer
Nov 19, 2026
Merged

Birfy merged 2 commits into
mainfrom
agent/site-chat-footer

Conversation

@HugoXK

@HugoXK HugoXK commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

Refs #1126 (follow-up to the merged #1127).

What changed

  • Footer: the chat panel now ends with the risk notice — DeepWiki is third-party and model-generated; verify load-bearing answers against the source — instead of MCP setup. MCP setup belongs with the integration docs, so it moved behind the header info icon and the guide link.
  • Guide links: both in-panel guide links (the header info icon and the footer Caveats) now derive their base from the loaded script — new URL('../deepwiki/', SELF.src).href — instead of a root-absolute href="/deepwiki/". GitHub Pages serves this site under /agentdescent/ while a local build sits at /, so the root-absolute form rendered in CI and 404'd on Pages. With no script element there is no safe base, so both anchors are left out rather than pointed at a literal.
  • Follow-ups: the last two question/answer turns are included as context in the next question, so a follow-up like "and where is that implemented?" works; New chat clears the history.
  • Stop / Retry: the typing state has a Stop action (AbortController); stopped or failed questions get a Retry action.
  • Mobile: the composer respects env(safe-area-inset-bottom) and the log uses overscroll-behavior: contain.
  • Only docs/assets/deepwiki.js, docs/assets/deepwiki.css and one site test change; no engine or page changes.

Verification at the tip

Tip SHA: befe705

Red first, base 48360631 with only the new test rows: 1 failed, 2 passed —
FAILED tests/test_site_navigation.py::test_deepwiki_links_derive_their_base_from_the_script_url.

Ran:

  • pytest -q tests/test_site_navigation.py at this tip -> 3 passed
  • node --check docs/assets/deepwiki.js -> pass
  • mkdocs build --clean --strict (social plugin excluded on this host: it needs cairo) -> pass, 12.17 s
  • python tests/test_site_navigation.py site -> 148 rendered documentation pages pass
  • python -m tools.gen_api_docs --check -> docs/api.md is up to date

Not run:

  • social cards and Playwright layout — the docs workflow runs both on this PR
  • full pytest -q — the tests workflow runs it on this PR

grep -c 'href="/deepwiki/"' docs/assets/deepwiki.js -> 0, and
test_deepwiki_links_derive_their_base_from_the_script_url pins that plus both
anchors being built from GUIDE.

Screenshots

Before = built main 76223fda; after = built this tip befe7053. Both builds
served under a real /agentdescent/ subpath so the GitHub Pages layout is
exercised, launcher clicked, #dw-panel captured. Evidence branch:
evidence/1144 @ 974f8ffc.

1440 px viewport

Before (1440 px) — the footer points at a root-absolute /deepwiki/, which 404s under the Pages subpath:

Before, 1440 px viewport

After (1440 px) — the same panel at this tip:

After, 1440 px viewport

390 px viewport

Before (390 px):

Before, 390 px viewport

After (390 px):

After, 390 px viewport

Capture notes: 1440 / 390 in the captions are the browser viewport widths, not
the image widths.
The capture script sets viewport={"width": width, "height": 900}
with device_scale_factor left unset (devicePixelRatio = 1, so 1 CSS px = 1 image px)
and then screenshots the #dw-panel element instead of the full viewport. Each image
is therefore a 1:1 crop of the panel at that viewport — 410 px wide at 1440, 360 px wide
at 390 (width: min(410px, calc(100vw - 1.5rem))) — which is why the files are narrower
than the viewport they were taken at. Nothing is resampled.

Measured in the same runs: before, the footer href was /deepwiki/ → 404
under /agentdescent/ (the header link did not render at all); after, header
and footer both resolve to …/agentdescent/deepwiki/ → 200, and under a
root serve both give /deepwiki/ → 200.

Merge to main deploys https://thinkflowlab.github.io/agentdescent/.

The chat footer now says what a reader needs (third-party, model-generated, verify the source) instead of "MCP setup"; MCP lives behind the header info icon and the /deepwiki/ page. Follow-ups include the last two Q/A turns, the typing state can be stopped, failures can be retried, and the composer respects the mobile safe area.
@HugoXK HugoXK added area:docs Documentation site (docs/, mkdocs.yml) and README documentation Improvements or additions to documentation labels Nov 17, 2026
@github-actions github-actions Bot added risk:T1 Risk tier T1 (tests, examples, changelog.d), set by the controller from the diff agent-pr Pull request opened by an agent labels Nov 17, 2026
@Birfy

Birfy commented Nov 17, 2026

Copy link
Copy Markdown
Collaborator

Review (Birfy)

Tip SHA: 4836063
Ran:

  • .github/scripts/risk_gate.py --pr 1144 → T1 (84 lines / 2 files)
  • node --check docs/assets/deepwiki.js → pass
  • live check: https://thinkflowlab.github.io/deepwiki/ → 404; https://thinkflowlab.github.io/agentdescent/deepwiki/ → 200
  • CI at this tip → required checks green (build, test 3.9–3.13); otel-wire SUCCESS; deploy skipped; risk tier and reviewed tip are report-only SUCCESS
    Not run:
  • mkdocs build --strict locally — the CI build job is green at this tip
  • Playwright layout locally — the docs workflow ran it on this PR
  • Full offline suite locally — the CI test matrix is the line
  • Ark real-model run — no model path changed
    Findings:
  • The new header info link and the footer "Caveats" link both use href="/deepwiki/". On the production site (site_url: https://thinkflowlab.github.io/agentdescent/) that path 404s; the real page is /agentdescent/deepwiki/. Local and CI mkdocs serve at /, so Playwright would not catch this. The same href was already in the footer on main; this PR adds a second copy in the header and the stated goal is to send readers to that page (MCP setup / caveats). Please derive the site base so both links work on GitHub Pages and locally — for example from the loaded assets/deepwiki.js script src — rather than hard-coding a root-absolute /deepwiki/.
    Verdict: FAIL

@HugoXK HugoXK removed the agent-pr Pull request opened by an agent label Nov 18, 2026
@github-actions github-actions Bot added the agent-pr Pull request opened by an agent label Nov 18, 2026
@HugoXK HugoXK removed the agent-pr Pull request opened by an agent label Nov 19, 2026
@github-actions github-actions Bot added the agent-pr Pull request opened by an agent label Nov 19, 2026
@HugoXK HugoXK removed the agent-pr Pull request opened by an agent label Nov 19, 2026
@github-actions github-actions Bot added the agent-pr Pull request opened by an agent label Nov 19, 2026
GitHub Pages serves the docs under /agentdescent/, while CI and a local
build serve them at /. The chat panel's header info link and footer
"Caveats" link were root-absolute (/deepwiki/), so they 404 on Pages and
no local run can see it.

Take the site root from the loaded assets/deepwiki.js script instead and
build <root>/deepwiki/ from it, so both links resolve under a subpath and
at the root. Without a script element there is no safe base, so the two
anchors are omitted rather than pointed at a literal that 404s.

Only the link base changes: no credentials are added, and the escaping
order in inline()/escapeHtml is untouched.
@HugoXK

HugoXK commented Nov 19, 2026

Copy link
Copy Markdown
Collaborator Author

Tip SHA: befe705
Base: 4836063 (parent; ahead 1 / behind 0)

Ran:

  • Fresh clone at the tip (git init + fetch --depth=2 agent/site-chat-footer), HEAD = befe705, tree clean; git diff 48360631...HEAD = 2 files, docs/assets/deepwiki.js +11/−2, tests/test_site_navigation.py +11/−0 (+22/−2 total).
  • Static, asset: grep -c 'href="/deepwiki/"' docs/assets/deepwiki.js → 0; the only deepwiki/ occurrence is :15 new URL('../deepwiki/', SELF.src).href : null; SELF :14; both anchors gated GUIDE ? … : '' (:48 header info, :71 footer Caveats); no literal fallback. With SELF null, GUIDE is null and both anchors are empty strings — pinned structurally by the two ternaries plus the test's occurrence count, not by executing the JS.
  • Red first: worktree at base 48360631 with only the 11 new test lines → 1 failed, 2 passed in 0.26s; sole failure test_deepwiki_links_derive_their_base_from_the_script_url, assert 'href="/deepwiki/"' not in … at tests/test_site_navigation.py:65.
  • Tip: python -m pytest -o addopts="" -q -p no:cacheprovider tests/test_site_navigation.py → 3 passed in 0.20s; node --check docs/assets/deepwiki.js → pass (node v22.23.2).
  • Docs build: mkdocs build --strict with the social plugin removed from a temporary config (it needs cairo) → success, 11.18 s; python tests/test_site_navigation.py site → Demo navigation verified on 148 rendered documentation pages; grep -rl 'href="/deepwiki/"' site/ → 0 files; the built asset carries var GUIDE = SELF ? and pages load src="assets/deepwiki.js".
  • python -m tools.gen_api_docs --check → docs/api.md is up to date; python -m tools.changelog_fragments check → 64 changelog fragment(s) OK.
  • Escape order untouched: escapeHtml :145 → inline() escape :151 → link rewrite :155, rel="noopener" on generated links. Credential surface: no api[_-]?key, token, Authorization or proxy match; the only endpoint is https://mcp.deepwiki.com/mcp (:6), unchanged by this diff.
  • CI at this sha (own read of /actions/runs/44497767173/jobs and the PR check runs; all 10 settled): test (3.9) 09:59:36Z, test (3.10) 09:54:48Z, test (3.11) 09:49:52Z, test (3.12) 09:50:44Z, test (3.13) 09:53:03Z — all success; build 09:36:38Z, otel-wire 09:36:33Z, reviewed tip (report only) 09:35:30Z, risk tier (report only) 09:35:20Z — success; deploy skipped. No leg was red.
  • Screenshots, mechanical only (this seat cannot read images — the model declares no image input): all four body URLs resolve; PNG magic and dimensions 410×668 / 410×680 at 1440 and 360×707 / 360×748 at 390; the downloaded files' git blob SHAs equal the evidence/1144 @ 974f8ffc files (d571dfa8…, c02311ee…, 645707f6…, 5a0d7eac…); per-pixel RGB diff on the common crop is non-zero — 14 663 px of 410×668 at 1440 and 39 687 px of 360×707 at 390. That is my count on the common crop; it differs from the 14 297 / 37 501 quoted elsewhere because of the comparison method, and it is not visual confirmation.

Not run:

  • Full offline pytest -q (the five test legs run it on 3.9–3.13).
  • Social card rendering and Playwright screenshot capture (the social plugin needs cairo, not installed here) — the docs workflow ran both on this PR.
  • Visual confirmation of the screenshots: no image input on this seat, so the pair is verified by dimensions, PNG validity, blob identity and pixel diff, not by eye.
  • A live request against https://thinkflowlab.github.io/agentdescent/ (no github.io egress from this box).

Non-blocking: the diff adds no changelog fragment, although changelog_fragments check passes on this base (64 OK).

Verdict: PASS

@Birfy

Birfy commented Nov 19, 2026

Copy link
Copy Markdown
Collaborator

Review (Birfy)

Tip SHA: befe705
Ran:

  • .github/scripts/risk_gate.py --pr 1144 → T1 (104 lines / 3 files vs main)
  • node --check docs/assets/deepwiki.js → pass
  • pytest -q tests/test_site_navigation.py → 3 passed
  • python -m tools.changelog_fragments check → 64 fragment(s) OK
  • URL resolution: new URL('../deepwiki/', 'https://thinkflowlab.github.io/agentdescent/assets/deepwiki.js').href → https://thinkflowlab.github.io/agentdescent/deepwiki/; a local /assets/deepwiki.js → /deepwiki/; a query string on the script src is ignored
  • grep: no href="/deepwiki/" in docs/assets/deepwiki.js; both in-panel anchors (header info and footer Caveats) are gated on GUIDE
  • CI at this tip (befe705) → required checks green (build, test 3.9–3.13); otel-wire SUCCESS; deploy skipped; risk tier and reviewed tip are report-only SUCCESS
    Not run:
  • mkdocs build --strict locally — the CI build job is green at this tip
  • Playwright layout locally — the docs workflow ran it on this PR
  • Full offline suite locally — the CI test matrix is the line
  • Ark real-model run — no model path changed
    Findings:
  • The previous FAIL at 4836063 (root-absolute href="/deepwiki/" 404s on GitHub Pages) is addressed: GUIDE is derived from the loaded script URL, both anchors use it, and the new test pins the absence of the literal plus the two GUIDE hrefs. The rest is the existing footer/risk-notice, follow-up context, Stop/Retry, and mobile safe-area work; no credentials or escape-order changes.
  • Non-blocking: no changelog.d/1144-*.md fragment for this user-visible site change; changelog_fragments check still passes.
    Verdict: PASS

@Birfy
Birfy merged commit 72eabc6 into main Nov 19, 2026
10 checks passed
@Birfy
Birfy deleted the agent/site-chat-footer branch November 19, 2026 10:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agent-pr Pull request opened by an agent area:docs Documentation site (docs/, mkdocs.yml) and README documentation Improvements or additions to documentation risk:T1 Risk tier T1 (tests, examples, changelog.d), set by the controller from the diff

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants