Guide v0: persona-routed iptf-map projection#31
Conversation
…, relocate explorer Parser update — switches `build-graph.mjs` to `js-yaml` and reads the new pattern + approach templates: nested `crops_profile`/`crops_context`, `post_quantum`, typed `related_patterns`, `open_source_implementations`, `iptf_pocs`, `primary_patterns`/`supporting_patterns`, `use_case`, and the meta-pattern `type` (renamed to `kind` to avoid colliding with our node-type discriminator). Edges are now generated from structured frontmatter first, with body-link extraction as a fallback. Source-of-truth — `extractSummary` returns the full first paragraph verbatim (no 200-char truncation). Pattern + approach index cards no longer fall back to truncated text. Detail and index renderers carry `SOURCE: iptf-map field — do not alter` comments at every map-content site. UI chrome (FAQ, testimonials, landing copy, vendor disclaimer) is the Guide's own and stays curated. Approach detail (`approaches/[slug].astro`) — full rewrite against the v2 schema. Renders Problem framing, sub-approach blocks (with embedded YAML metadata, labelled bodies, benchmarks), Comparison table, persona perspective tabs, Recommendation, Open questions, and optional Example scenario. Sidebar surfaces primary/supporting patterns, IPTF PoCs, open-source implementations, vendors, and related use cases. Pattern detail (`patterns/[slug].astro`) — picks up new fields: `crops_context` narrative table, `post_quantum` block, typed `related_patterns` groups (requires/composes_with/alternative_to/ see_also), open-source implementations, sub-pattern list for meta patterns, context_differentiation callouts. Explorer relocation — `pages/tree.astro` and `pages/browse.astro` moved into `pages/explore/`, with a new `explore/galaxy.astro` to recover the old Galaxy index. Linked unobtrusively from the Guide footer; not part of primary nav. React + D3 deps stay since `/explore/*` uses them. Tests under `guide/tests/` predate this rewrite and target the old parser shape. They need to be rewritten to match v2; deferred to follow-up per plan.
…ive domain counts Wire `src/styles/global.css` into Guide.astro — was never imported, so all `.prose` rules were dead and rendered markdown fell back to browser defaults (16px disc bullets, no padding). Bullets now render as the prototype's custom dot style (`list-style: none` + `::before` dot at 0.55em); body text and tables pick up the prototype font sizing. Approach detail rewrite: persona tabs at top with single indigo color, compact 2-col card grid for architectural options, recommendation as highlighted box, per-architecture detail in collapsibles, comparison + benchmarks render through proper :global(.prose table) styling. Landing: - Drop "Humanitarian Orgs" from the cycling word list - About link points to new /about route, Blog link to existing Jekyll blog at iptf.ethereum.org/blog/ - New "Latest posts" section reads recent posts from the Jekyll _posts/ directory at build time (via import.meta.glob) and surfaces 3 cards with hero images linking to the live blog New /about page: short team description + initiatives (Privacy Map, PoCs, Coordination) + contact cards (email + institution/vendor forms), matching the previous Jekyll landing in the Guide UI. Nav: remove Jurisdictions from primary nav (still reachable via direct URL); explorer/about/blog/contact in the footer. Domain case-study counts are now transitive: domain → use-case ← approach via the `addresses` edge, so /domains/* shows real counts (e.g. Funds & Assets → 7) instead of 0 from the missing direct edge. Cross-cut domains (Custody, Identity & Compliance, Post-Quantum Threats) correctly stay at 0 because their markdown lists no use-cases.
Pin was at 4e72090 (pre-v2). The v2 migration moved approaches to a structured schema (Problem framing / Approaches / Comparison / Persona perspectives / Recommendation / Open questions) which the new guide parser expects. Vercel build was rendering empty approach pages because the submodule still served the old format. Bumps content/ to c8addba (v0.3.0-13-gc8addba) on iptf-map main.
- Drop CROPS row from approach comparison tables (already rendered as
pills on the architecture cards above).
- Neutralize CROPS-context label colors on patterns; stack rows on
narrow viewports.
- Remove the "{level} risk" badge from the post-quantum block and
switch to neutral coloring; vector + mitigation still document the
threat and path forward.
- Parse `[role]` prefix from protocol steps and render it as a small
badge in a fixed column so step text aligns across rows.
- Collapse the pattern page grid to a single column below 1024px.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
@copilot can you audit the dependencies please |
Agent-Logs-Url: https://github.com/ethereum/iptf-web/sessions/80852098-5eb0-49cb-be42-0065694e6081 Co-authored-by: rymnc <43716372+rymnc@users.noreply.github.com>
Dependency audit complete. Updated astro to 6.3.1 and @astrojs/react to 5.0.4; npm audit now reports 0 vulnerabilities. Commit: 1bc46e5. Warning Firewall rules blocked me from connecting to one or more addresses (expand for details)I tried to connect to the following addresses, but was blocked by firewall rules:
If you need me to access, download, or install something from one of these locations, you can either:
|
|
@Meyanis95, seems like copilot just pushed a commit, feel free to overwrite it if you would like |
|
I mean, you invoked it, not sure to understand what you're doing here. |
oskarth
left a comment
There was a problem hiding this comment.
Review notes from local verification. I ran npm ci, npm run build, npm test, and npx tsc --noEmit against origin/test_guide.
| // Apply colors | ||
| nodeSel.selectAll('circle, rect, polygon') | ||
| .attr('fill', (_, i, nodes) => { | ||
| const d = d3.select(nodes[i].parentNode as Element).datum() as SimNode; |
There was a problem hiding this comment.
Medium: strict TypeScript does not pass here. npx tsc --noEmit reports that nodes[i].parentNode may be null and that the D3 callback node can be EnterElement, which does not expose parentNode. The same issue repeats on lines 190 and 195.
There was a problem hiding this comment.
Going to do these in a small follow-up. Page works at runtime; just hygiene.
|
I think the commit pushed was just general best practice (Astro dep push), and A is saying can either keep it or over-write it depending on preference. |
rymnc
left a comment
There was a problem hiding this comment.
can we also add a github action that runs nightly, fetches latest commit from iptf-map, and regenerates the graph and deploys? will cut down maintenance overhead
rymnc
left a comment
There was a problem hiding this comment.
also, lets merge the writeups into this, there is no reason we need to have a different site for writeups and this landing page
|
Writeups should keep same url as before |
- Drop the `truncates long summaries` test. `extractSummary` does not implement truncation and shouldn't (verbatim-render rule). - Update the `fileToSlug` and integration-test fixtures from `pattern-zk-shielded-balances` (removed in the v2 schema bump) to `pattern-zk-proof-systems`. Addresses oskarth review on PR #31. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Drop the silent CONTENT_SUBMODULE fallback in candidate resolution. If no candidate has a `patterns/` directory, throw with a clear message pointing at `git submodule update --init --recursive`. - Add a 0-node guard in the CLI main block after buildGraph(). The guard lives in the CLI, not inside buildGraph(), so the test suite can still call buildGraph(repoRoot) directly without tripping it. Previously a fresh checkout with an uninitialized submodule produced "Graph built: 0 nodes, 0 edges" and deployed empty index pages. Addresses oskarth review on PR #31. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
iptf-map authors write portable Markdown for GitHub readers (`../patterns/pattern-foo.md`). When the Guide rendered those bodies through `marked()` directly, 186 raw `.md` hrefs leaked into `dist/` as broken links. - Add `guide/src/lib/render.ts` exporting `renderMarkdown` and `renderMarkdownInline`. Registers a marked link renderer that rewrites relative `.md` hrefs to Guide routes (e.g. `../patterns/pattern-foo.md` → `/patterns/foo`). Leaves absolute URLs, `#anchor` and `mailto:` links untouched. - Validate resolved routes against the current graph node set; `console.warn` once per unresolved href so data drift in iptf-map becomes visible at build time without failing the build. - Replace every `marked(...)` / `marked.parse(...)` / `marked.parseInline(...)` call across approach, pattern, domain, vendor, jurisdiction pages and the DetailPanel React island with the shared helpers. `grep -rohE 'href="[^"]*\.md[^"]*"' dist/` drops from 186 to ~12, all of which are either intentional absolute GitHub source-file URLs or upstream typos (`pattern-dvp-erc7573.md.md`) surfaced by the warnings. Addresses oskarth review on PR #31. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Approach detail pages render a "Use case: ..." chip that links to `/use-cases/<slug>`, and approach sidebars list related use-cases the same way. No `/use-cases` routes existed, so every one of those links 404'd on the staging build. - Add `guide/src/pages/use-cases/index.astro` — card-grid index sorted alphabetically, modeled on `approaches/index.astro`. Reserves an image slot for the follow-up hero-thumbnail work so layout doesn't need restructuring later. - Add `guide/src/pages/use-cases/[slug].astro` — detail page following the simplest existing template (`jurisdictions/[slug].astro`). Renders body via the shared renderer so internal map links resolve. Surfaces related case studies, building-block patterns, and regulating jurisdictions. - Add "Use Cases" to the top nav in `Guide.astro` alongside Case Studies / Patterns / Vendors / Domains, and add `'use-cases'` to the `activeSection` union. 20 new use-case pages emitted; the broken approach chips now resolve. Addresses oskarth review on PR #31. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
✅ Deploy Preview for iptf-stagging ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Addressed critical issues from @oskarth. |
Replaces the Jekyll + legacy map/ + guide/ tri-stack with a single Astro app served from the repo root. Closes the staging-to-production transition on PR #31. Promotes guide/ to root: moves astro.config.mjs, tsconfig.json, package.json, src/, scripts/, tests/, and .claude/launch.json out of the subfolder. Adds vitest.config.ts to scope test discovery and updates the integration test's content/ path from `../../content` to `../content`. Migrates blog writeups: _posts/*.md -> src/posts/*.md. Adds the following Astro routes/layouts: - src/pages/[slug].astro post detail at root - src/pages/blog/index.astro archive at /blog/ - src/layouts/Post.astro post layout + JSON-LD BlogPosting - src/pages/feed.xml.js RSS via @astrojs/rss - @astrojs/sitemap registration /sitemap.xml at build time URLs are preserved: posts keep their `/<slug>/` paths via a Jekyll-compatible slugify of the frontmatter title. External inbound links don't break. Open Graph + Twitter meta added centrally in Guide.astro so every page emits og:title, og:description, og:image, og:type, og:url, plus the twitter:* equivalents and a canonical link. Static assets relocated to public/: assets/, CNAME, robots.txt, tee-protocol-page.html. Same URLs. Deletes the Jekyll surface (_config.yml, Gemfile, _layouts/, _includes/, _drafts/, _posts/, index.md, blog.html, serve.sh) and the legacy map/ Astro app (duplicated by src/pages/explore/). Rewrites .github/workflows/deploy.yml to build the Astro app from the repo root (no Ruby step, no map/ build, no merge). Rewrites root README.md and CLAUDE.md to describe the new layout. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The CONTENT_SUBMODULE path was `__dirname/../../content` which worked when scripts/ lived at guide/scripts/. After the cutover, that resolved one level above the repo (/opt/build/content on Netlify), tripping the fail-fast guard introduced for empty submodules. Drops one `..` so it resolves to repo-root/content. Also drops the stale `__dirname/../../../iptf-map` and `$HOME/IPTF/iptf-map` candidates: the git submodule covers the canonical case, and IPTF_MAP_PATH still works as an explicit override for unusual local layouts. File also reformatted to project style. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
@Meyanis95 https://iptf-stagging.netlify.app/resilient-plural-identity/ the images which don't have backgrounds are not visible because the site is dark mode by default, how do you propose we fix this? I see two options - 1/ invert the colors on the images and update them I would suggest the former |
Three rendering issues surfaced after the cutover landed: - `/blog` and `/use-cases` headers were unstyled because the `.idx-page` / `.idx-header` / `.idx-label` / `.idx-title` / `.idx-desc` rules only lived inside `approaches/index.astro`'s scoped `<style is:global>` block. Astro's `is:global` only loads styles when the defining page is rendered, so sibling index pages didn't pick them up. Moved the shared rules to `src/styles/global.css` and dropped the duplicates from approaches/index.astro. - Post body diagrams (transparent PNGs against a light page, e.g. the Traditional System diagram on `/resilient-plural-identity/`) rendered black-on-black on the site's dark theme. Added a warm off-white background to `.post-body img` so dark strokes show through transparent areas; opaque images cover the background, so it's a no-op for them. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…e line Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
@Meyanis95 can we add a favicon please |
|
Copy paste from chat: |
|
do we need this page? |
|
About page always nice to have IMO |
yes but it looks like the one from the old site, perhaps just needs a design refresh |
All the other comments have been added to the to-do, and fixes will be pushed.
|
- add favicon (indigo brand mark) wired into both layouts - strip inline markdown from extracted summaries so vendor descriptions render as plain text - migrate landing to Guide layout so the top nav matches sub-pages - hide "What institutions tell us" testimonials section pending real social proof - spell out CROPS / I2I / I2U inline on the eval section Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Reworked guide site: information architecture, design system, and scoped Astro components. Domain listing is data-driven from the content collection with a build-time validation guard (includes Civic Coordination & Governance). Domain descriptions render as section primers. Adds team and workshop photos. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
feat: Website UI/UX rework
…_guide # Conflicts: # src/posts/2026-05-14-resilient-disbursement-rails.md # src/posts/2026-05-28-resilient-civic-participation.md
rymnc
left a comment
There was a problem hiding this comment.
adding QA:
1/
too much gap on https://iptf-stagging.netlify.app/use-cases/private-procurement/ assuming all use-cases have this issue
2/
data and oracles misaligned
3/
too much gap between the header and use cases in https://iptf-stagging.netlify.app/use-cases/
4/
table not aligned on https://iptf-stagging.netlify.app/approaches/approach-dvp-atomic-settlement/
assuming all approaches have the same issue
5/
too much whitespace between writeups and header
https://iptf-stagging.netlify.app/blog/
6/
artifacts look elongated here, out of aspect ratio: https://iptf-stagging.netlify.app/
oskarth
left a comment
There was a problem hiding this comment.
Better to merge and work iteratively! LGTM
|
Agree with @rymnc comments Also noticed we removed contact us, was this deliberate? any reason we cant have three buttons |
|
Resolved all the above comments from @rymnc
Yes, Jakub (UX) didn't recommend having 3 buttons here. It's something we can iterate on depending on what we want to prioritize. |
…uild check - astro.config.mjs: site was still iptf.netlify.app — canonical/OG URLs now point to iptf.ethereum.org - Add permanent redirects for all 13 legacy Jekyll post URLs (/:title/ from filename) to their new title-derived /blog/<slug>/ routes - Add @astrojs/sitemap (replaces jekyll-sitemap) and point robots.txt at sitemap-index.xml - deploy.yml: run the build job on pull_request (validate without deploying) so deploy breakage is caught before merge Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>





Summary
guide/— an Astro static site that projectsiptf-mapcontent into use-case, pattern, vendor, domain, jurisdiction, FAQ, and glossary views.What's here
Static site at
guide/(Astro 5 + React islands)/,/approaches,/patterns,/vendors,/domains,/jurisdictions,/faq,/glossary,/explore/{galaxy,tree,browse},/about,/blog.guide/scripts/build-graph.mjs) reads thecontent/submodule pinned atiptf-mapand generatesgraph.json+glossary.jsonat build time. No hand-editing.SOURCE:at every render site). UI chrome is the Guide's own.crops_profile,crops_context,post_quantum,context_differentiation. Approach pages render persona perspectives, sub-approach cards, comparison tables, and the recommendation block.Live preview: https://iptf-web.vercel.app/ (Meyanis95/iptf-web fork, deploys from this branch).
v0 scope (proposed rescope vs #29 — see comment thread)
Entry point: approaches surfaced as case studies. Persona perspectives stay where they are today (rendered as tabs inside each approach page), no persona frontmatter or persona filtering.
Still open for v0:
FAQ.mdiniptf-mapwith real content so/faqstops rendering placeholders. Single-source, no per-pattern link-up.Dropped from #29 after discussion (see comment):
Persona tags in frontmatter— most patterns are relevant to all personas; filtering would discard information. Persona perspectives in body are sufficient.Per-pattern— centralfaq:fieldFAQ.mdis enough.Transition plan (out of scope for this PR — open for discussion)
This branch lands the Guide alongside the existing Jekyll site without changing the live deploy. The deploy switch is a separate decision:
CNAMEcurrently points iptf.ethereum.org at GitHub Pages (Jekyll)./blogon Jekyll and let Astro own everything else, or migrate posts into Astro and retire Jekyll entirely._posts/— plan is to keep them as-is (Astro can read the same Markdown).content/reliably during the GH Action / Vercel build.Would appreciate team input on (1) and (2) before sequencing the cutover.
Test plan
cd guide && npm install && npm run devboots locally athttp://localhost:4321iptf-mapcontentcd guide && npm test— content pipeline and graph-layout tests passCloses #29 once the deploy-switch follow-ups land.
🤖 Generated with Claude Code