Skip to content

docs(user-guide): add guide for bringing an application to codemie - #402

Open
alex-budanov wants to merge 4 commits into
codemie-ai:mainfrom
alex-budanov:docs/EPMCDME-14751-add-an-application
Open

docs(user-guide): add guide for bringing an application to codemie#402
alex-budanov wants to merge 4 commits into
codemie-ai:mainfrom
alex-budanov:docs/EPMCDME-14751-add-an-application

Conversation

@alex-budanov

@alex-budanov alex-budanov commented Sep 10, 2026

Copy link
Copy Markdown

Summary

Adds a user-guide page for teams that want their own product to appear as an application tile in CodeMie. Written for the team bringing the product, not for the operator: it covers whether an application tile is even the right mechanism, the link/iframe/module choice, the YAML entry, what to test, and a pre-submission checklist.

Replaces the approach in #396 (closed). That PR added a 330-line admin-side guide; this one is a shorter user-guide page, reviewed against the codebase and against a live deployment rather than written from the spec.

Changes

  • Adds docs/user-guide/applications/add-an-application.md (~1,880 words)
  • Updates docs/user-guide/applications/index.md to describe what an application is and link to the new guide
  • Adds the Applications category to the user-guide sidebar, which was previously unreachable by navigation (the section's index.md existed but nothing pointed to it)
  • Adds SAMEORIGIN and AIMF to the cspell dictionary

Testing

  • Tested locally with npm start
  • All pages render correctly
  • Images display properly
  • Internal links work
  • Sidebar navigation works

Verified via npm run build, which fails on broken links and unresolvable sidebar ids, and by inspecting the generated HTML. Not verified in a browser: no browser tooling in this repo, so layout was not visually reviewed. Checked on the built output instead: the 5-column table gets the theme's overflow: auto, and the task-list checkboxes render as standard disabled inputs. No images on this page.

Quality Checks

  • npm run check passes (typecheck + lint + commitlint)
  • No MDX compilation errors
  • No raw angle brackets (<text> must be `<text>`)
  • Sidebar references document IDs (not filenames)
  • Images stored locally next to content (not in static/img/)
  • Commit messages follow Conventional Commits
  • No secrets or credentials in documentation

Additional Notes

Every behavioural claim was checked against codemie and codemie-ui, and the examples against the live GET /v1/applications on a running deployment. Corrections to the earlier draft:

  • An application is not a left-navigation item. The left nav gets one Applications entry, gated on at least one enabled app; each product is a tile on the page behind it. Confirmed visually against a live instance.
  • description is the tile's body text, not its subtitle. The subtitle is by <created_by>, and it is omitted when created_by is unset.
  • A malformed entry takes the whole Applications page down, and url, name and type all carry that blast radius, not url alone.

Examples are now the real registered applications (AICE, MF Lens, Technology Copilot) with their owning teams, plus one clearly labelled hypothetical for link. MF Lens gives the co-deployment path its first real example.

Open questions for the platform team, currently carried in the text as hedges rather than statements:

  1. Registration says "ask the operator where to send the entry" because the live customer-config.yaml is a ConfigMap managed outside this repo. This is now confirmed empirically: the live application list differs from the one in config/customer/customer-config.yaml, with two repo entries absent and two live entries that exist nowhere in this repository. No owner or channel is named anywhere, so the page cannot name one.
  2. A module runs on CodeMie's origin and can therefore call CodeMie's API as the signed-in user with nothing handed to it. Nothing registered today relies on this and it is not a documented contract. Whether it is intended needs an answer; if not, it is a security question rather than a feature.
  3. The production capability-reuse path appears to be a service key for CodeMie's LiteLLM proxy, which is what MF Lens uses. Confirming that this is the sanctioned route would let the page recommend it outright.
  4. frame-ancestors tells iframe authors to name "CodeMie's host" without giving a value, because none is published in the chart or nginx config. Both live iframes sidestep this by being served from a path on CodeMie's own host; whether that routing is generally available to new teams is unclear.
  5. The module and co-deployment checklists require sign-off that names no approver and no place to record it.
  6. One live application (KFAB) has created_by: null, no deployment guide, and no mention anywhere in these repositories. It is a registered tile with no recorded owner, which is exactly what the checklist's "named owner" item exists to prevent.
  7. The repository's default customer-config.yaml would fail this guide's own checklist on all three entries: two http://localhost URLs, an unpinned entry, and two empty descriptions. Worth fixing as config hygiene, since it is the first thing anyone copies.

Co-deployment is described and given a checklist but has no procedure; it may belong in a separate admin-side page.

Aleksandr Budanov added 4 commits September 10, 2026 15:38
Adds a plain-language guide for teams registering their own product as
an application tile, covering the link/iframe/module choice, the YAML
entry, what to test, and a pre-submission checklist.

Also adds the Applications category to the user-guide sidebar, which
was previously unreachable by navigation.
The audience line said "already built its own product", which excluded
teams building a panel specifically for CodeMie. That is the reader the
module type and the capability-reuse section serve, and the module
example in the same page already addresses them.
…guidance

Replaces the invented scenarios with AICE, MF Lens and Technology
Copilot, named with their owning teams, plus one clearly labelled
hypothetical for the link type. MF Lens also gives the co-deployment
path its first real example.

Capability reuse now leads with the pattern actually in production, a
service key for CodeMie's LiteLLM proxy, rather than the same-origin
module session that nothing currently relies on.

The login paragraph said only that CodeMie passes no identity. It now
says how to get single sign-on: register a client with the same
identity provider the deployment uses.
The section promised three options and then presented a fourth thing in
a bold paragraph. Co-deployment is orthogonal to the render type, not a
fourth type, so the heading drops the count and co-deployment gets a
subsection a reader can scan to. The cross-reference earlier in the page
now resolves to a visible heading.

Also renames "Real-world examples" to "Examples", since one of the four
entries is a labelled hypothetical.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant