feat(bar): add Get CCS Bar dashboard banner and ccs bar docs page

Add a 'Get CCS Bar' promo banner + card to the dashboard (mirroring the
OpenRouter promo pattern + design system) so users discover the macOS menu-bar
app, with a macOS-aware install CTA. Add a user-facing docs/ccs-bar.md covering
what it is, install via 'ccs bar install', launch, what it shows, uninstall,
and the loopback requirement -- closing the docs-sync gap for the new ccs bar
command.

docs/ccs-bar.md

@@ -0,0 +1,84 @@
+# CCS Bar — Native macOS Menu Bar App
+
+CCS Bar is a native macOS menu-bar app that shows live subscription quota and usage at a glance for your Claude Code, Codex, and CLIProxy accounts, without opening the dashboard.
+
+## What It Is
+
+CCS Bar is a thin client of the CCS local web-server. It never talks to a provider directly: every call goes to `localhost`, and CCS performs any provider fetch server-side. Opening the menu fires a debounced force-refresh so the glance reflects live data without blocking the UI.
+
+It is macOS only.
+
+## What It Shows
+
+- Per-account quota percent and reset countdown
+- Account tier
+- Today, 7-day, and 30-day cost
+- A 30-day usage sparkline
+- Account state (active, paused, default)
+- Native subscription rows for Claude Code and Codex
+
+## Requirements
+
+- macOS
+- CCS CLI installed and configured (`ccs config` works)
+- The CCS web-server reachable on loopback. `ccs bar` (or `ccs bar launch`) starts it for you.
+
+## Install
+
+```bash
+ccs bar install
+```
+
+This downloads `CCS-Bar.app.zip` from the floating `ccs-bar-latest` GitHub release and installs `CCS Bar.app` into `~/Applications`. Downloads are restricted to `github.com` and `objects.githubusercontent.com`, and extraction is guarded against zip-slip.
+
+### Gatekeeper note
+
+The v1 builds use ad-hoc signing, so the first launch may be blocked by Gatekeeper. Either right-click the app and choose Open, or clear the quarantine attribute:
+
+```bash
+xattr -dr com.apple.quarantine "$HOME/Applications/CCS Bar.app"
+```
+
+## Launch
+
+```bash
+ccs bar          # alias: ccs bar launch
+```
+
+This makes sure the web-server is up, writes the discovery file `~/.ccs/bar.json`, and opens the app. The discovery file looks like this:
+
+```json
+{ "baseUrl": "http://127.0.0.1:3000", "port": 3000, "authMode": "loopback" }
+```
+
+The Swift app reads `~/.ccs/bar.json` to find the server.
+
+## Loopback / Localhost Requirement
+
+CCS Bar talks only to `http://127.0.0.1:<port>`. v1 supports `authMode: "loopback"` only, meaning dashboard auth disabled on localhost.
+
+If you bind the dashboard beyond localhost (for example `--host` set to a non-loopback address) with dashboard auth disabled, the bar's read endpoints (`GET /api/bar/summary`, `GET /api/bar/analytics`) are refused for non-loopback callers, and the app cannot reach the server. Keep the dashboard on loopback for CCS Bar to work.
+
+## Uninstall
+
+```bash
+ccs bar uninstall
+```
+
+This removes `~/Applications/CCS Bar.app` and the installed version pin. It is a no-op if the app is not present.
+
+## Troubleshooting
+
+- Server failed to start: usually a port conflict. Free the port or re-run `ccs bar` to pick a fresh one.
+- App won't open (Gatekeeper): right-click and Open, or clear quarantine with the `xattr` command above.
+- Blank app: the web-server is not running. Re-run `ccs bar` and confirm `~/.ccs/bar.json` exists.
+- Quota not updating: re-open the menu to force a refresh, or confirm the server is still reachable on loopback.
+
+## Development
+
+The source lives in `macos-bar/`. Contributors can build and run the logic checks with a Swift 5.9+ toolchain (CommandLineTools is enough, full Xcode not required):
+
+```bash
+swift build                 # build all targets, including the app
+swift run ccs-bar-check     # run the logic tests
+```

ui/src/components/profiles/ccs-bar-banner.tsx

@@ -0,0 +1,101 @@
+/**
+ * CCS Bar Feature Banner
+ * Dismissible announcement banner promoting the native macOS menu-bar app.
+ *
+ * Rendered only on macOS: the CTA is an install action (`ccs bar install`) that
+ * has no effect on other platforms, so showing it elsewhere would be misleading.
+ */
+
+/* eslint-disable react-hooks/set-state-in-effect */
+import { useState, useEffect } from 'react';
+import { useTranslation } from 'react-i18next';
+import { X, MonitorDot, ExternalLink } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+
+const BANNER_DISMISSED_KEY = 'ccs:ccs-bar-banner-dismissed';
+
+// User-facing docs page for CCS Bar (flat Markdown in the ccs/cli docs tree).
+const CCS_BAR_DOCS_URL = 'https://github.com/kaitranntt/ccs/blob/main/docs/ccs-bar.md';
+
+// Lightweight, dependency-free macOS detection. Kept inline because no other
+// component needs platform detection; a shared hook would be premature.
+const isMacOS =
+  typeof navigator !== 'undefined' &&
+  /Mac|iPhone|iPad/i.test(navigator.userAgent || navigator.platform || '');
+
+interface CcsBarBannerProps {
+  onInstallClick?: () => void;
+}
+
+export function CcsBarBanner({ onInstallClick }: CcsBarBannerProps) {
+  const { t } = useTranslation();
+  const [dismissed, setDismissed] = useState(true); // Start hidden to avoid flash
+
+  // Check localStorage on mount
+  useEffect(() => {
+    const isDismissed = localStorage.getItem(BANNER_DISMISSED_KEY) === 'true';
+    setDismissed(isDismissed);
+  }, []);
+
+  const handleDismiss = () => {
+    localStorage.setItem(BANNER_DISMISSED_KEY, 'true');
+    setDismissed(true);
+  };
+
+  if (!isMacOS) return null;
+  if (dismissed) return null;
+
+  return (
+    <div className="bg-gradient-to-r from-accent to-accent/90 text-white px-4 py-3 relative shrink-0">
+      <div className="flex items-center justify-between gap-4 max-w-screen-xl mx-auto">
+        <div className="flex items-center gap-3 flex-1 min-w-0">
+          <div className="p-1.5 bg-white/20 rounded-md shrink-0">
+            <MonitorDot className="w-4 h-4" />
+          </div>
+          <div className="flex-1 min-w-0">
+            <p className="font-medium text-sm">
+              {t('ccsBarBanner.new')}: {t('ccsBarBanner.title')}
+            </p>
+            <p className="text-xs text-white/80 truncate">
+              {t('ccsBarBanner.description')}{' '}
+              <code className="bg-white/15 rounded px-1 py-0.5 font-mono text-[11px]">
+                ccs bar install
+              </code>
+            </p>
+          </div>
+        </div>
+
+        <div className="flex items-center gap-2 shrink-0">
+          {onInstallClick && (
+            <Button
+              size="sm"
+              variant="secondary"
+              onClick={onInstallClick}
+              className="bg-white text-accent hover:bg-white/90 h-8"
+            >
+              {t('ccsBarBanner.install')}
+            </Button>
+          )}
+          <a
+            href={CCS_BAR_DOCS_URL}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="text-xs text-white/80 hover:text-white hidden sm:flex items-center gap-1"
+          >
+            Learn more
+            <ExternalLink className="w-3 h-3" />
+          </a>
+          <Button
+            size="icon"
+            variant="ghost"
+            onClick={handleDismiss}
+            className="h-7 w-7 text-white/70 hover:text-white hover:bg-white/20"
+          >
+            <X className="w-4 h-4" />
+            <span className="sr-only">Dismiss</span>
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}

ui/src/components/profiles/ccs-bar-promo-card.tsx

@@ -0,0 +1,53 @@
+/**
+ * CCS Bar Promo Card
+ * Permanent promotional card for the native macOS menu-bar app, shown in the
+ * providers sidebar footer.
+ *
+ * Rendered only on macOS: the install CTA has no effect elsewhere.
+ */
+
+import { useTranslation } from 'react-i18next';
+import { Button } from '@/components/ui/button';
+import { MonitorDot } from 'lucide-react';
+
+// Lightweight, dependency-free macOS detection (see ccs-bar-banner.tsx).
+const isMacOS =
+  typeof navigator !== 'undefined' &&
+  /Mac|iPhone|iPad/i.test(navigator.userAgent || navigator.platform || '');
+
+interface CcsBarPromoCardProps {
+  onInstallClick: () => void;
+}
+
+export function CcsBarPromoCard({ onInstallClick }: CcsBarPromoCardProps) {
+  const { t } = useTranslation();
+
+  if (!isMacOS) return null;
+
+  return (
+    <div className="p-3 border-t bg-gradient-to-r from-accent/5 to-accent/10 dark:from-accent/10 dark:to-accent/15">
+      <div className="flex items-center gap-2">
+        <div className="p-1.5 bg-accent/10 dark:bg-accent/20 rounded shrink-0">
+          <MonitorDot className="w-4 h-4 text-accent" />
+        </div>
+        <div className="flex-1 min-w-0">
+          <p className="text-xs font-medium text-accent dark:text-accent-foreground">
+            {t('ccsBarPromo.title')}
+          </p>
+          <p className="text-[10px] text-muted-foreground truncate">
+            {t('ccsBarPromo.description')}
+          </p>
+        </div>
+        <Button
+          size="sm"
+          variant="ghost"
+          onClick={onInstallClick}
+          className="h-7 px-2 text-accent hover:text-accent hover:bg-accent/10 dark:hover:bg-accent/20"
+        >
+          <MonitorDot className="w-3 h-3 mr-1" />
+          <span className="text-xs">{t('ccsBarPromo.install')}</span>
+        </Button>
+      </div>
+    </div>
+  );
+}

ui/src/components/profiles/index.ts

@@ -20,5 +20,10 @@ export { OpenRouterModelPicker } from './openrouter-model-picker';
 export { OpenRouterPromoCard } from './openrouter-promo-card';
 export { OpenRouterQuickStart } from './openrouter-quick-start';
 export { AlibabaCodingPlanPromoCard } from './alibaba-coding-plan-promo-card';
+
+// CCS Bar (native macOS menu-bar app) promo components
+export { CcsBarBanner } from './ccs-bar-banner';
+export { CcsBarPromoCard } from './ccs-bar-promo-card';
+
 export { ModelTierMapping } from './model-tier-mapping';
 export type { TierMapping } from './model-tier-mapping';

ui/src/lib/i18n.ts

@@ -2475,6 +2475,17 @@ const resources = {
         title: 'OpenRouter',
         description: 'Access hundreds of models from one API endpoint.',
       },
+      ccsBarBanner: {
+        new: 'NEW',
+        title: 'CCS Bar for macOS',
+        description: 'See live subscription quota and usage from your menu bar. Install with',
+        install: 'Install',
+      },
+      ccsBarPromo: {
+        title: 'CCS Bar (macOS)',
+        description: 'Live quota and usage in your menu bar.',
+        install: 'Install',
+      },
       profileCard: {
         profile: 'Profile',
         openRouter: 'OpenRouter profile',

ui/src/pages/api.tsx

@@ -22,6 +22,8 @@ import { OpenRouterBanner } from '@/components/profiles/openrouter-banner';
 import { OpenRouterQuickStart } from '@/components/profiles/openrouter-quick-start';
 import { OpenRouterPromoCard } from '@/components/profiles/openrouter-promo-card';
 import { AlibabaCodingPlanPromoCard } from '@/components/profiles/alibaba-coding-plan-promo-card';
+import { CcsBarBanner } from '@/components/profiles/ccs-bar-banner';
+import { CcsBarPromoCard } from '@/components/profiles/ccs-bar-promo-card';
 import {
   useProfiles,
   useDeleteProfile,
@@ -41,6 +43,15 @@ import { useTranslation } from 'react-i18next';
 import { toast } from 'sonner';
 import { useNavigate } from 'react-router-dom';
 
+// CCS Bar is installed via the `ccs bar install` CLI command, not from the
+// dashboard. The promo CTA therefore opens the user-facing docs page where the
+// install/launch steps live, rather than triggering an in-app action.
+const CCS_BAR_DOCS_URL = 'https://github.com/kaitranntt/ccs/blob/main/docs/ccs-bar.md';
+
+function openCcsBarDocs() {
+  window.open(CCS_BAR_DOCS_URL, '_blank', 'noopener,noreferrer');
+}
+
 export function ApiPage() {
   const { t } = useTranslation();
   const navigate = useNavigate();
@@ -213,6 +224,7 @@ export function ApiPage() {
   return (
     <div className="flex h-full min-h-0 flex-col overflow-hidden">
       <OpenRouterBanner onCreateClick={() => setCreateDialogOpen(true)} />
+      <CcsBarBanner onInstallClick={() => openCcsBarDocs()} />
       <div className="flex-1 flex min-h-0 overflow-hidden">
         <div className="w-80 border-r flex flex-col bg-muted/30">
           <div className="p-4 border-b bg-background">
@@ -363,6 +375,7 @@ export function ApiPage() {
               setCreateDialogOpen(true);
             }}
           />
+          <CcsBarPromoCard onInstallClick={() => openCcsBarDocs()} />
         </div>
 
         <div className="flex min-h-0 flex-1 flex-col min-w-0 overflow-hidden">