Merge pull request #115 from friuns2/codex/skills-tab-npx-find

Add Composio and Skills search to Directory Hub

Author: friuns2

.agents/skills/codex-app-parity/SKILL.md

@@ -14,6 +14,15 @@ Ensure behavior is implemented with Codex.app as the source of truth, then verif
 
 ## Project Instructions
 
+## Repo Knowledge Maintenance
+
+For user-visible Directory, Skills, Apps, Plugins, MCP, or Composio changes in this repo:
+
+- Update `tests.md` with manual verification steps, including light and dark theme checks.
+- If the change creates or changes durable behavior/architecture, add or update an `llm-wiki/raw/...` source and corresponding `llm-wiki/wiki/...` concept page.
+- Keep `whatToTest.md` as a short pending-only checklist; remove items that were actually executed successfully.
+- Prefer assertions plus screenshots for browser validation; screenshots alone are not enough.
+
 ## Codex.app-First Development Policy
 
 For every **new feature** and every **behavior/UI change**, treat the installed desktop app as the source of truth:

llm-wiki/raw/features/directory-hub-composio-skills-search.md

@@ -0,0 +1,69 @@
+# Directory Hub Composio and Skills Search Source
+
+Date: 2026-05-02
+
+## Scope
+
+This source records the Directory Hub work that made `#/skills` a native Skills/Apps surface with:
+
+- a default `Skills` tab,
+- MCPs shown immediately before installed skills,
+- registry search backed by `npx skills find`,
+- registry install backed by `npx skills add <source> --yes --global`,
+- Composio connector browsing/auth/detail flows,
+- stronger light/dark verification and edge-case tests.
+
+## Skills Tab Behavior
+
+- `#/skills` defaults to the `Skills` tab.
+- Other directory tabs are shareable through `?tab=plugins`, `?tab=apps`, `?tab=composio`, and `?tab=skills`.
+- The first-launch Plugins card still routes to `?tab=plugins`.
+- The top-level `Refresh` button only shows `Refreshing...` for explicit user-triggered refreshes.
+- Opening or switching to the Skills tab lists MCPs without forcing an MCP reload; explicit `Refresh` performs the reload behavior.
+- MCPs are shown above installed skills and use the same card/grid section style.
+
+## Installed Skills and Registry Search
+
+- The Find skills panel calls `/codex-api/skills-hub/search`, which runs `npx skills find`.
+- Installed detection uses the same installed skills source as the Skills Hub list, including RPC/plugin/shared skills.
+- Search result cards preserve registry identity while carrying installed local state.
+- Opening an installed search result switches to the local installed skill record/content/actions.
+- Find skills cards hide the local folder browse affordance to avoid mixing remote registry identity with local-only controls.
+- Installed skills cards hide redundant `Installed`, `Disabled`, and repeated `local` labels.
+- Installed skills cards show descriptions parsed from local `SKILL.md` files.
+- Installed entries are assembled concurrently when reading local descriptions.
+- Registry installs run `npx skills add <source> --yes --global`.
+- Install success requires a non-empty, validated local `SKILL.md` path; the UI treats missing path or missing post-refresh local skill as failure instead of showing a remote registry card as installed.
+
+## Composio Directory Behavior
+
+- The Composio tab prefers `npx --yes composio` and falls back to the installed CLI only when needed.
+- Login uses `composio login --no-browser -y`; the UI opens a browser tab from the click and navigates it to the returned auth URL.
+- The Composio workspace card shows current account/org/backend status.
+- Connector cards show connector details such as tool counts, auth/connection state, and concrete descriptions.
+- Connector details show overview chips, connection rows, useful tools, dashboard action, connect/login action, and `Try it!` where applicable.
+- Composio search sends the server query parameter as `query`.
+- Search ranking prioritizes exact connector slug/name matches above connectors that only mention the query in their descriptions; this keeps `Instagram` ahead of `Meta Ads` for `instagram`.
+
+## Test Coverage and Artifacts
+
+- Unit coverage was added for Composio connector sorting:
+  - exact slug/name query matches outrank description-only matches,
+  - connected connectors rank first when no query is active.
+- Gateway unit coverage verifies Composio connector search sends `query`, `cursor`, and `limit`.
+- Manual/browser verification captured light and dark screenshots for:
+  - Skills tab,
+  - installed skill modal,
+  - Composio connector search/detail.
+- Remaining `whatToTest.md` items require environment states that are not always safe to force:
+  - unavailable Composio CLI when neither `npx --yes composio` nor installed CLI can run,
+  - final login URL navigation in a real unauthenticated browser flow.
+
+## Important Commits
+
+- `d18776b9` - optimized Skills tab default and query-tab routing.
+- `1f67ba71` - required local skill path after install.
+- `6fa62670` - showed local skill descriptions.
+- `21217108` - streamlined Skills tab loading and avoided implicit MCP reload.
+- `5cedb0c8` - clarified refresh state and Composio search ranking.
+- `3c8e3823` - added Directory edge-case tests.

llm-wiki/wiki/concepts/directory-hub-composio-skills.md

@@ -0,0 +1,87 @@
+# Directory Hub, Composio, and Skills Search
+
+This page documents the current Directory Hub behavior under `#/skills`, especially the native Skills tab, Composio connector browsing, and registry-backed Skills search.
+
+## Route Model
+
+- `#/skills` opens the Directory Hub with the `Skills` tab selected by default.
+- The active tab is URL-addressable with `?tab=plugins`, `?tab=apps`, `?tab=composio`, or `?tab=skills`.
+- The Directory route name remains `Skills`; the inner surface title remains `Skills & Apps`.
+- The first-launch Plugins card explicitly opens `?tab=plugins`.
+
+## Skills Tab
+
+The Skills tab is ordered for local use:
+
+1. GitHub Skills Sync controls.
+2. Find skills registry search.
+3. MCP section.
+4. Installed skills section.
+
+Important behavior:
+
+- MCPs appear immediately before installed skills.
+- Normal tab navigation only lists MCPs; the top-level `Refresh` button is the explicit MCP reload path.
+- Installed skill cards are local-first: no repeated `local`, `Installed`, or `Disabled` labels on the card grid.
+- Installed card descriptions are parsed from local `SKILL.md` files.
+- Installed entries are built concurrently so description reads do not add one round trip per skill.
+
+## Skills Registry Search
+
+The Find skills panel is backed by the published skills CLI:
+
+- Search runs `npx skills find`.
+- Install runs `npx skills add <source> --yes --global`.
+- Install success is only valid when a local installed `SKILL.md` path is returned and validates.
+- If install does not produce a local path or the post-refresh installed list does not include the skill, the UI treats it as failure.
+
+Search result identity is intentionally hybrid:
+
+- Cards keep registry owner/source details.
+- Installed matches get local path/enabled state.
+- Opening an installed result switches to the local installed skill detail and actions.
+- Search result cards hide the local folder browse icon; local browse remains available in installed skill details.
+
+## Composio
+
+The Composio tab is CLI-backed and should feel like a native Directory section.
+
+- Prefer `npx --yes composio`; fall back to the installed CLI only when needed.
+- Login runs `composio login --no-browser -y`.
+- The UI opens a browser tab from the click, then navigates it to the CLI auth URL.
+- The workspace card shows account/org/backend status.
+- Connector cards show real details: tool counts, descriptions, connection status, and auth actions.
+- Connector detail shows overview, connections, useful tools, dashboard link, connect/login action, and `Try it!` when usable.
+
+Search ranking has a specific edge-case rule:
+
+- Exact slug/name matches outrank description-only matches.
+- Example: searching `instagram` should show the `Instagram` connector before `Meta Ads`, even though Meta Ads mentions Instagram and may have more tools.
+
+## Testing Lessons
+
+Use assertions, not screenshots alone.
+
+Recommended checks:
+
+- `#/skills` defaults to Skills.
+- `?tab=` routes to the selected tab.
+- Normal Skills navigation does not call MCP reload.
+- The refresh button only says `Refreshing...` during explicit manual refresh.
+- Installed search results open local detail actions.
+- Failed installs do not create installed UI state.
+- Composio search sends `query`, preserves pagination params, and ranks exact matches first.
+- Light and dark screenshots should include both the Skills page and long installed-skill modal content.
+
+Unit tests now cover:
+
+- Composio exact query ranking over description-only matches.
+- Connected Composio connector ordering without a query.
+- Gateway query/cursor/limit params for Composio connector search.
+
+## Related Pages
+
+- [Entity: codex-web-local](../entities/codex-web-local.md)
+- [Concept: Skills route UI](./skills-route-ui.md)
+- [Overview](../overview.md)
+- [Source: Directory Hub Composio and Skills Search](../../raw/features/directory-hub-composio-skills-search.md)

llm-wiki/wiki/entities/codex-web-local.md

@@ -16,13 +16,16 @@
 - Realtime chat rendering uses cached markdown/highlight output and bridge-side inline media sanitization to keep browser payloads bounded
 - User-visible UI work is expected to include dark-theme verification, not only light-theme checks
 - Worktree dev startup may reuse a shared `node_modules` tree; forcing reinstall is not always the right default
+- Directory Hub is the `#/skills` surface for Plugins, Apps, Composio, MCPs, Skills search, and installed local skills
 
 ## Source links
 - [Source snapshot](../../raw/projects/codex-web-local.md)
 - [Integrated terminal source](../../raw/features/integrated-terminal.md)
+- [Directory Hub Composio and Skills search source](../../raw/features/directory-hub-composio-skills-search.md)
 - [Realtime chat rendering source](../../raw/features/realtime-chat-rendering-inline-media.md)
 - [Skills route UI + first-launch card source](../../raw/features/skills-route-ui-and-first-launch-card.md)
 - [Integrated terminal concept](../concepts/integrated-terminal.md)
+- [Directory Hub, Composio, and Skills Search concept](../concepts/directory-hub-composio-skills.md)
 - [Realtime chat rendering concept](../concepts/realtime-chat-rendering.md)
 - [Merge-to-main workflow concept](../concepts/merge-to-main-workflow.md)
 - [Skills route UI concept](../concepts/skills-route-ui.md)

llm-wiki/wiki/index.md

@@ -8,13 +8,15 @@
 
 ## Concepts
 - [concepts/integrated-terminal.md](./concepts/integrated-terminal.md): Codex.app-style integrated xterm/PTY terminal architecture, edge cases, and verification.
+- [concepts/directory-hub-composio-skills.md](./concepts/directory-hub-composio-skills.md): Directory Hub tab routing, Composio connector behavior, Skills search/install semantics, and edge-case testing.
 - [concepts/merge-to-main-workflow.md](./concepts/merge-to-main-workflow.md): branch integration and conflict-resolution workflow.
 - [concepts/opencode-zen-big-pickle.md](./concepts/opencode-zen-big-pickle.md): OpenCode Zen Big Pickle model configuration for Codex CLI and OpenCode CLI.
 - [concepts/realtime-chat-rendering.md](./concepts/realtime-chat-rendering.md): realtime chat rendering, sync-churn reduction, and inline media sanitization.
 - [concepts/skills-route-ui.md](./concepts/skills-route-ui.md): Skills route naming, first-launch Plugins card persistence, dark-theme fixes, and verification lessons.
 
 ## Sources
 - [../raw/features/integrated-terminal.md](../raw/features/integrated-terminal.md): source facts for the integrated terminal implementation and follow-up tests.
+- [../raw/features/directory-hub-composio-skills-search.md](../raw/features/directory-hub-composio-skills-search.md): source facts for Directory Hub, Composio connectors, Skills search/install, and edge-case tests.
 - [../raw/features/realtime-chat-rendering-inline-media.md](../raw/features/realtime-chat-rendering-inline-media.md): source facts for realtime chat rendering and inline media sanitization.
 - [../raw/features/skills-route-ui-and-first-launch-card.md](../raw/features/skills-route-ui-and-first-launch-card.md): source facts for the Skills route rename, first-launch Plugins card, dark-theme fix, and dev-server workflow adjustment.
 - [../raw/projects/codex-web-local.md](../raw/projects/codex-web-local.md): immutable source snapshot for project facts.

llm-wiki/wiki/log.md

@@ -1,5 +1,11 @@
 # Log
 
+## [2026-05-02] ingest | Directory Hub Composio and Skills search
+- Added source: `raw/features/directory-hub-composio-skills-search.md`.
+- Created wiki page: `concepts/directory-hub-composio-skills.md`.
+- Documents: Skills tab default/query routing, MCP placement/reload behavior, `npx skills find/add` semantics, Composio CLI-backed connector behavior, search-ranking edge cases, and verification coverage.
+- Updated `overview.md`, `entities/codex-web-local.md`, and `index.md`.
+
 ## [2026-04-26] ingest | skills route UI and first-launch plugins card
 - Added source: `raw/features/skills-route-ui-and-first-launch-card.md`.
 - Created wiki page: `concepts/skills-route-ui.md`.

llm-wiki/wiki/overview.md

@@ -9,16 +9,19 @@ This wiki tracks knowledge about the `codex-web-local` project and related workf
 - Codex.app-style integrated terminal implementation and tests
 - Realtime chat rendering performance and inline media sanitization
 - Skills route UI, first-launch Plugins card behavior, and dark-theme verification lessons
+- Directory Hub tab routing, Composio connector behavior, and Skills registry search/install semantics
 
 ## Primary source
 - [codex-web-local project snapshot](../raw/projects/codex-web-local.md)
 - [integrated terminal implementation source](../raw/features/integrated-terminal.md)
+- [directory hub Composio and Skills search source](../raw/features/directory-hub-composio-skills-search.md)
 - [realtime chat rendering and inline media source](../raw/features/realtime-chat-rendering-inline-media.md)
 - [skills route UI and first-launch card source](../raw/features/skills-route-ui-and-first-launch-card.md)
 
 ## Linked pages
 - [Entity: codex-web-local](./entities/codex-web-local.md)
 - [Concept: Integrated terminal](./concepts/integrated-terminal.md)
+- [Concept: Directory Hub, Composio, and Skills Search](./concepts/directory-hub-composio-skills.md)
 - [Concept: Realtime chat rendering](./concepts/realtime-chat-rendering.md)
 - [Concept: Merge-to-main workflow](./concepts/merge-to-main-workflow.md)
 - [Concept: Skills route UI](./concepts/skills-route-ui.md)

src/App.vue

@@ -1479,7 +1479,7 @@ function dismissFirstLaunchPluginsCard(): void {
 
 function onOpenPluginsHomeCard(): void {
   dismissFirstLaunchPluginsCard()
-  void router.push({ name: 'skills' })
+  void router.push({ name: 'skills', query: { tab: 'plugins' } })
 }
 
 const threadContextBadgeState = computed(() => {

src/api/codexGateway.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
-import { startThreadTurn } from './codexGateway'
+import { listDirectoryComposioConnectors, startThreadTurn } from './codexGateway'
 
 function mockRpcFetch(): { requests: Array<{ method: string, params: Record<string, unknown> }> } {
   const requests: Array<{ method: string, params: Record<string, unknown> }> = []
@@ -60,3 +60,30 @@ describe('startThreadTurn collaboration mode payloads', () => {
     })
   })
 })
+
+describe('listDirectoryComposioConnectors', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it('sends search queries as query params expected by the server', async () => {
+    const requests: string[] = []
+    vi.stubGlobal('fetch', vi.fn(async (input: RequestInfo | URL) => {
+      requests.push(String(input))
+      return new Response(JSON.stringify({
+        data: [],
+        nextCursor: null,
+        total: 0,
+      }), {
+        status: 200,
+        headers: {
+          'Content-Type': 'application/json',
+        },
+      })
+    }))
+
+    await listDirectoryComposioConnectors('instagram', '50', 25)
+
+    expect(requests).toEqual(['/codex-api/composio/connectors?query=instagram&cursor=50&limit=25'])
+  })
+})