docs(config): add application onboarding guide and plain-language companion - #411
Open
alex-budanov wants to merge 13 commits into
Open
alex-budanov wants to merge 13 commits into
alex-budanov wants to merge 13 commits into
Conversation
added 11 commits
September 9, 2026 20:03
Documents the decision process, YAML registration schema gotchas, Module Federation contract, and review checklist for registering a third-party product as an Application tile — content that previously only existed as a developer guide inside the codemie backend repo, unpublished and unlinked from any docs site. Wires the previously orphaned user-guide/applications page into the sidebar and cross-links it with the new guide and with Customer Feature Configuration.
Code review on PR codemie-ai#396 found: a Sources link in the integrations-vs- applications FAQ was missing the integrations/integrations doc-id segment (404), and the review checklist plus known-gaps table used "entry" where the danger callout explicitly reserves that word for the API response field, not the YAML field a reviewer is actually checking. Also aligns the arguments field description between the two docs.
…text Replace the rewritten guide body with the exact content from codemie!EPMCDME-14469_applications-onboarding-guide, keeping only the Docusaurus front matter. Drops the impersonal-voice rewrite, admonition conversion, schema deduplication against customer-feature-configuration.md, and the entry/url terminology fix applied in the prior two commits.
Fixes a register mismatch ("your thing"), a self-contradicting
Module Federation exposes-key example now confirmed by reading
@originjs/vite-plugin-federation's source directly, an
overclaimed dev-override feature that hasn't shipped anywhere yet,
a British/American spelling inconsistency, and a couple of
run-on sentences.
Retitle section 1 to match what it covers, since two thirds of it explained registration mechanics rather than the build-or-not decision. Correct the routing framing. The section split mechanisms by "assistant side" versus application, but a registered MCP server is not assistant-only: the managed catalog is client-neutral and is provisioned into agent clients and the codemie-code CLI. The split is now capability-that-gets-called versus UI-a-person-opens, which names no consumer and stays true as clients are added. Other corrections and readability fixes: - "no API" becomes "no registration API". A read API exists and section 4 refers to it twice; what is absent is any way to register via API, since config writes reject undeclared components. - Name GCP and Azure in the ConfigMap inconsistency instead of describing them anonymously, so a reader can tell whether the warning applies to them. - Generalize the tiebreak, which sent readers to build an MCP server even when the other applicable row was Skill or Workflow. - Break the 130-word config-precedence paragraph into two bullets plus the instruction, and drop the "Not this" table column, whose four cells restated the header. - Thin the bold, which covered three spans in four sentences. Claude-Session: https://claude.ai/code/session_01S88R2iND5WD4UvXwAhx6uU
Correct the axis error. The flowchart routes D1=yes straight to J3 without asking D2, yet J3's type is "any" and the callout below tells that reader their type drives the security review. Say explicitly that landing on J3 still requires answering D2. The journey table encoded the same error through its "+" convention, which chains J1 into J2 into J3 and so charged a co-deployed link with a hosted remote bundle, a frontend review, and architecture sign-off it does not need. J3's cells are now self-contained and name the module conditional. J2 keeps its "+", which is correct there. Also: - Drop the six-stage vocabulary. It was asserted twice, defined nowhere, had no section for "agree", and listed test before review while the guide reviews at section 5 and tests at section 6. - Remove the hardcoded Mermaid palette. It was the only diagram of the site's three that hardcoded colors, so it alone would not follow the light/dark toggle, and it painted decision and outcome nodes identically. - Trim the diagram nodes to journey and type. Timeline and sign-off were duplicated in the table and had already drifted from it. - Reword "the shape X runs today", and unbacktick AICE, a product name whose config id is lowercase aice. Claude-Session: https://claude.ai/code/session_01S88R2iND5WD4UvXwAhx6uU
The worked example and the review checklist both told readers to expose `./CodemieEntryComponent`, which section 4 already warns will fail. The host passes 'CodemieEntryComponent' verbatim to getRemote (codemie-ui, ApplicationFederationPage.tsx:30 and :85), and vite-plugin-federation 1.4.1 does a literal moduleMap lookup with no ./ normalization, so a prefixed key throws "Can not find remote module CodemieEntryComponent". A team could follow the example, pass the checklist, and ship a module that never mounts. Both places now name the bare key, and the checklist flags the leading ./ since that is the whole trap. "Each tier includes the ones above it" was also wrong. The iframe tier is entirely about being framed: frame-ancestors, third-party cookies, frame-breakout. None of it reaches a module, which is never in a frame. Section 5 now states the real composition, and the worked example names the two tiers that actually apply to it. Also: - Cut the meta-commentary explaining why the worked example references later sections, and the reassurance about unfamiliar terms. The pointer to section 4 stays. - Move the "you" and "CodeMie" definition from section 3 into the header block, three sections ahead of where it was and before first use. - Drop the timeline and sign-off from worked-example step 1. They duplicated the journey table, had drifted from it, and contradicted step 6 of the same list. Claude-Session: https://claude.ai/code/session_01S88R2iND5WD4UvXwAhx6uU
…in section 4 The styling paragraph claimed a standard build that injects CSS into document.head "works out of the box". Verified against codemie-ui with a throwaway vitest probe on observeAndMoveStyles: that holds on first open only. The util caches, and restores on later mounts, exclusively stylesheet links matching /assets/style-*.css, removing them from document.head to do so. Nothing else is cached. Since the remote is imported once per page load, navigating away and back yields a fresh shadow root with no re-injection to copy, so an injected <style> or a link named assets/index-<hash>.css, which is Vite's default, is simply gone. The probe saw exactly one stylesheet and zero style elements on the second mount. The paragraph now leads with that and names the one delivery form that survives. The ?path= deep link was described as appending a query string to the entry. The host reads path from its own URL and concatenates the raw value with no separator (ApplicationIframePage.tsx:28-36), so the value must carry its own leading / or ?. A reader following the old wording would build their app to parse a query parameter that never arrives. The exposes-key callout still surveyed two forms as though the answer were open. It is settled: vite-plugin-federation 1.4.1, the pinned version, does a literal moduleMap lookup, and the ./ form throws "Can not find remote module CodemieEntryComponent". The callout now states the rule and quotes the error, matching sections 3 and 5. Also drop "the single most expensive typo available here". Omitting name, type or description produces the same 500, and omitting enabled stops the backend starting, which is strictly worse. Claude-Session: https://claude.ai/code/session_01S88R2iND5WD4UvXwAhx6uU
…n gaps Section 5 asked reviewers to confirm entry "resolves from the operator's network". Section 4 says the opposite in bold: reachable from the user's browser, not from the backend, which only echoes the string. The two readings agree for most deployments and diverge for J3, where a team deploying into the operator's cluster could tick the box truthfully with a service DNS name that resolves from no browser anywhere. Section 3's trust-tier row assigns green to link, yellow to iframe, red to module. Section 5 then used green for "All types", so an iframe or module submitter who learned green means link could skip the universal items. Green becomes white there, and the two places that referenced it follow. Section 7 gains two gaps that are real in current code and ticketed together: link dispatch still calls window.open(entry, '_blank') with no noopener (ApplicationsPage.tsx:45), and ?path= is still concatenated onto entry without an origin check (ApplicationIframePage.tsx:36). Section 6 step 2 now says GET /v1/applications needs no authentication, so a plain curl works. Verified at every layer: no global dependencies on the app, dependencies=[] on the router, no Depends on the endpoint, and none of the six middlewares authenticates. Without this a developer assumes a token is needed and skips the step, which is exactly where a malformed entry would have been caught before it blanked the page. Also drop the example URL added to the ?path= sentence last commit. It read /applications/your-slug, but ?path= is read by ApplicationIframePage at applications/iframe/:slug, so the example pointed at the module route where nothing reads it. The rule is kept; the example is gone rather than corrected, leaving no URL to drift against router.tsx. Claude-Session: https://claude.ai/code/session_01S88R2iND5WD4UvXwAhx6uU
… gaps - Adds user-guide/applications/add-an-application.md, a plain-language companion to the Application Onboarding Guide, wired into the sidebar and cross-linked from the applications index and API docs. - Adds six items to applications-onboarding.md verified against origin/main of codemie and codemie-ui: the mount()/unmount() teardown race, the full YAML-to-API field mapping, the exact application routes and slug constraint, availableForExternal being silently inert for applications, the rolling-restart replica window, the missing removal path, and the narrow declarations API not covering applications.
Adds a one-line caption under the placeholder YAML block in both the Application Onboarding Guide and the plain-language guide, naming AICE (and MF Lens, in the plain-language guide) as real apps registered with the same shape. Keeps the template itself generic so it can't go stale the way the earlier Technology Copilot example did.
12 tasks
added 2 commits
September 14, 2026 18:54
The audience line said "already built its own product", which excluded teams building a panel specifically for CodeMie. That reader is served by the module type and the capability-reuse section already on this page.
…oarding guide The iframe-redirect / keycloakConfigPath mechanism was only ever demonstrated by an example application that has since been removed from production, and no platform code implements or examines that field. State only the confirmed fact (no identity/token/session is passed) instead.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Supersedes #396 (closed, was on a now-abandoned branch) and #402 (an earlier, less-corrected draft — see note below). Fresh branch off current
main, no rebase conflicts since main hasn't moved since divergence.module, a review checklist, and known platform gaps.codemiebackend repo (unpublished, unlinked from any docs site, only reachable by browsing that repo's source tree).user-guide/applications/add-an-application.md, a plain-language companion page for teams deciding whether/how to add their product, deferring to the onboarding guide for exact schema/API details.user-guide/applications/index.mdpage into the sidebar (it had no sidebar entry at all) and cross-links it with both new guides.admin/configuration/codemie/customer-feature-configuration.mdanduser-guide/api/index.md.applications-onboarding.mdagainstorigin/mainofcodemieandcodemie-ui(verified via dedicated read-only worktrees, not the locally checked-out feature branches): the asyncmount()/unmount()teardown race, the full YAML-to-API field mapping (id→slug,enabledfiltering,availableForExternalbeing dropped,descriptionnull→""), the exact application routes and theiframe-slug constraint,availableForExternalbeing silently inert for applications specifically, the rolling-restart replica-disagreement window, the missing removal/ownership-transfer path, and the narrowPUT /v1/config/declarations/{id}API not covering applications.argumentsinto the template, so the example can't go stale.Note on #402
#402's
add-an-application.mdwas an earlier draft with two claims this PR corrects: "AICE... framed from a path on CodeMie's own host" (unverifiable against source, dropped) and atechnology-copilotmodule example (the app no longer exists in production). #402 also has a couple of independent wording improvements this branch doesn't carry over —give co-deployment its own headingandwiden application guide audience to new builds— worth a follow-up pass if their content is still wanted.Changes
docs/admin/configuration/codemie/applications-onboarding.md(new)docs/user-guide/applications/add-an-application.md(new)docs/admin/configuration/codemie/customer-feature-configuration.md— cross-link to the new guidedocs/user-guide/applications/index.md— links to both new guides; wired intosidebars.tsdocs/user-guide/api/index.md— cross-link to the plain-language guidedocs/user-guide/data-source/datasources-types/add-provider-datasource.md— note on the provider SDKsidebars.ts— both pages added under Admin → Configuration → CodeMie and User Manuals → Applicationsfaq/how-do-i-add-my-application-as-a-tile-in-codemie.md— links to the new plain-language guidefaq/whats-the-difference-between-an-application-and-an-integration-in-codemie.md(new)CLAUDE.md— documents the admonitions-in-.md-files conventioncspell.config.yaml— addsSAMEORIGINTesting
npm run checkpasses (typecheck, eslint, prettier, markdownlint, cspell, commitlint) — 0 errors across all checksnpm run buildcompletes locally — production build succeeds, static files generated, no broken-link errorsrealpathQuality Checks
npm run checkpasses (typecheck + lint + commitlint)