Flow updates

[rachellerathbone]

What

One-sentence summary of this PR.

Why

What problem this solves.

How

Brief technical approach.

Testing

What you tested and how to verify locally.

Checklist

• Follows the 7.04 open-source readiness checklist in project instructions
• No hardcoded secrets or internal-only references in user-facing content
• Lint, typecheck, and build pass locally
• Internal links and changed pages verified

What

Brief description of changes

Why

Why this change was needed

Testing

How to verify the changes

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
multicorn-learn	Ready	Preview, Comment	Apr 11, 2026 11:19am

[github-actions]

multicorn-ops review

Persona	Role	Primary	Status	Summary
Jordan	Security Auditor	yes	Concern	API key handling improvements are good, but inline key exposure in proxy example and string comparison bug create residual risks.
Priya	Open Source Contributor	yes	Concern	The quickstart flow is clearer but a string-comparison bug and a removed install step without explanation could trip up contributors.
Marcus	Design-Conscious Developer	yes	Concern	Links render nicely but the secondary button lacks a visible border on hover and the note text style may be too faint.
Sarah	Non-Technical Decision-Maker	yes	Passed	The revised copy is clearer and more action-oriented; the onboarding steps are now easier for a non-technical reader to follow.
The Team	Acquisition Due Diligence	yes	Concern	The string comparison bug, removed global install without docs update, and URL anchor change indicate shallow QA that would concern an acquirer.
Alex	Accessibility Advocate	yes	Concern	New link buttons open in _blank without an accessible label warning screen reader users, and focus ring uses opacity shorthand that may not render in all browsers.
Yuki	International User	yes	Concern	Most copy is clear and actionable, but the proxy note text is a dense run-on sentence that may be hard to parse for non-native English readers.

Concerns

Jordan (Security Auditor)

• components/HowItWorks.tsx:72 - The proxy step embeds 'MULTICORN_API_KEY=mcs_your_key_here' inline in a shell command example. Users may copy-paste and accidentally commit a real key in shell history or CI configs. The example should consistently show 'export MULTICORN_API_KEY=...' as a separate step rather than an inline assignment.
• app/shield/page.tsx:469 - String comparison 's.step <= '2'' uses lexicographic ordering on string step values. This is a logic bug (not a security issue per se) but if step numbers ever exceed single digits this silently mislabels code block languages, which could cause TypeScript to be rendered as Terminal or vice versa — a trust/confusion issue for auditors reading logs.
• content/docs/mcp-proxy.mdx:35 - URL changed from /settings/api-keys to /settings#api-keys (hash fragment). Verify the hash fragment correctly anchors to the API keys section; a broken anchor silently lands users on the settings root with no indication of where the key is, potentially leading to frustration or insecure workarounds.

Priya (Open Source Contributor)

• app/shield/page.tsx:469 - 's.step <= '2'' compares string values lexicographically rather than numerically. This is a latent bug and a code smell that will confuse contributors: '10' <= '2' is true in JS. Should use Number(s.step) <= 2 or compare against a set like ['1','2'].
• content/blog/shield-vs-mj-rathbun.mdx:119 - 'npm install -g multicorn-shield' was removed from the proxy bash snippet without a preceding install step. The blog post now shows 'npx multicorn-proxy init' with no prior installation context. New contributors or readers won't know how the binary is available.

Marcus (Design-Conscious Developer)

• components/HowItWorks.tsx:281 - Secondary link button uses 'hover:text-text-primary' but no background change on hover. This makes the interactive state feel unpolished — a background-color or underline on hover would make it clearer the element is clickable.
• components/HowItWorks.tsx:294 - Note text uses 'text-text-tertiary' at text-xs. On many monitors this will appear very faint and may not meet visual contrast expectations for instructional content that tells users where to get their API key.

The Team (Acquisition Due Diligence)

• app/shield/page.tsx:469 - Lexicographic string comparison 's.step <= '2'' is a correctness bug. It signals the step numbering scheme (string literals) is fragile and not type-safe. Steps should be numeric or compared with a typed guard.
• content/blog/shield-vs-mj-rathbun.mdx:119 - Removed 'npm install -g multicorn-shield' from the bash snippet without adding context. The blog post now instructs readers to run 'npx multicorn-proxy init' without installing the package. 'npx' will auto-install but this is implicit behavior that could break if the package name or registry changes.
• content/blog/what-your-ai-agent-did.mdx:130 - Same missing install step issue in the second blog post's bash snippet.
• content/docs/mcp-proxy.mdx:35 - URL path changed from /settings/api-keys to /settings#api-keys across multiple files. No evidence of redirect or anchor existence verified in the diff. A broken settings link in docs is a significant UX regression that no test in this diff would catch.

Alex (Accessibility Advocate)

• components/HowItWorks.tsx:278 - Links with target='_blank' open in a new tab but have no aria-label or visually hidden text indicating this. Screen reader users will hear 'Sign up, link' with no warning that activation opens a new tab, which violates WCAG 3.2.2 (On Input).
• components/HowItWorks.tsx:284 - focus:ring-2 focus:ring-primary/20 uses an opacity modifier on the ring color. Some browser/OS high-contrast modes may suppress low-opacity focus indicators entirely, effectively hiding the focus ring from keyboard users.
• components/HowItWorks.tsx:284 - focus:outline-none removes the native outline entirely and relies solely on the custom ring. If Tailwind's ring styles are purged or the primary color token is undefined, keyboard users will have no visible focus indicator at all.

Yuki (International User)

• components/HowItWorks.tsx:73 - The note 'Get your API key at app.multicorn.ai/settings#api-keys. Prefer a config file? Run npx multicorn-proxy init and pick "Local MCP / Other".' packs two separate instructions into one paragraph. Splitting into two sentences or bullet points would make each action clearer for non-native English readers.
• app/shield/page.tsx:458 - The updated note 'Prefer a config file? Run npx multicorn-proxy init and pick "Local MCP / Other".' uses a question-as-heading pattern that may not parse naturally for non-native speakers. A declarative alternative like 'To use a config file instead:' is more direct and translatable.

Open-Source Readiness Checklist

Code Quality

• All functions have clear, descriptive names — No new functions introduced; interface and variable names are descriptive.
• No hardcoded secrets, API keys, internal URLs, or employee names in code or comments — Placeholder API key strings like 'mcs_your_key_here' appear in quickstart code snippets and a PROXY_STEPS code example (e.g. 'MULTICORN_API_KEY=mcs_your_key_here npx ...'). These are illustrative placeholders, not real secrets, but the pattern of embedding a key-shaped string in source could confuse scanners or users. Real names (Scott Shambaugh) appear in blog content but in a journalistic context referencing a public incident.
• No // TODO without a public issue reference — No TODO comments introduced in the diff.
• No commented-out code blocks — No commented-out code blocks added.
• No debug logging (console.log, println) left in — No debug logging introduced.
• All any types eliminated (TypeScript) — New interfaces (FlowStepLink, FlowStep additions) are fully typed with no 'any'.
• [~] Error handling is complete — no swallowed exceptions, no empty catch blocks — No error-handling logic added or modified in this diff.
• No Atlassian-internal references, no proprietary patterns or terminology — No Atlassian references found.

Testing

• All new code has tests — New UI components and logic (FlowStepLink rendering, language mapping change s.step <= '2', new quickstart steps) have no accompanying test files in the diff.
• [~] Coverage meets or exceeds repo minimum — Coverage data not visible in the diff.
• [~] Tests pass locally and in CI — CI results not visible in the diff.
• [~] Edge cases and error paths are tested — Cannot assess without test files.
• [~] No flaky tests — Cannot assess from diff alone.

Security

• No secrets in code, comments, config files, or git history — Placeholder strings ('mcs_your_key_here') are illustrative, not real secrets. The diff also improves guidance by promoting process.env usage.
• [~] All user input is validated — No user-input handling introduced in this diff.
• [~] Dependencies audited — no known vulnerabilities — No dependency changes in this diff.
• HTTPS enforced for all external communication — All external links use https://.
• API keys/tokens never logged — No logging of API keys introduced; diff actually improves guidance to use environment variables instead of inline strings.

Documentation

• [~] README.md is accurate and up to date — README.md not modified; cannot verify accuracy from diff alone.
• [~] CONTRIBUTING.md is accurate and up to date — CONTRIBUTING.md not in diff.
• CHANGELOG.md updated with this change — No CHANGELOG.md update present in the diff.
• [~] New public APIs have JSDoc/KDoc with examples — No new public API functions introduced.
• Any new config options are documented — New FlowStepLink and FlowStep fields are documented inline via TypeScript interfaces and usage in MDX content.
• [~] Architecture decisions documented in ADR if significant — Changes are UI/copy updates, not architectural decisions.

Open Source Hygiene

• [~] Licence header present in source files (if required by licence) — Cannot determine licence header policy from this diff alone.
• [~] CODE_OF_CONDUCT.md present — Not verifiable from diff.
• [~] Issue templates are current — Not modified in diff.
• [~] PR template is current — Not modified in diff.
• No internal company references or links — All links point to public-facing URLs (app.multicorn.ai, GitHub, etc.).
• [~] Package name and description are correct in package.json — package.json not modified in diff.
• [~] Repository topics/tags are set on GitHub — Cannot verify from diff.

UX & Accessibility (UI changes only)

• [~] Works at 375px viewport width (mobile) — Cannot verify responsiveness from diff alone; new flex-wrap on link buttons is a positive signal.
• Keyboard navigable — New anchor elements are native tags, which are keyboard navigable by default; focus ring styles (focus:ring-2) are present.
• [~] Colour contrast meets WCAG AA — Cannot verify actual colour values (bg-primary, text-white, etc.) without knowing the design token values.
• [~] Loading states for async operations — No async operations introduced in this diff.
• [~] Error states are user-friendly (not raw error messages) — No error state UI introduced.
• [~] Animations respect prefers-reduced-motion — No animations introduced in this diff.

---

Advisory only. Does not block merge. Actions logged to Shield as pr_review and oss_check.