docs: align content with real behavior and add services page

Author: 0xbbuddha

package-lock.json

@@ -9,6 +9,7 @@
     "lint": "echo \"no lint configured\""
   },
   "dependencies": {
+    "highlight.js": "^11.11.1",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "react-router-dom": "^6.22.3"

package.json

@@ -0,0 +1,53 @@
+import React from 'react';
+
+type CalloutVariant = 'note' | 'tip' | 'warning';
+
+const calloutStyles: Record<CalloutVariant, string> = {
+  note: 'border-sky-500/30 bg-sky-500/10 text-sky-100',
+  tip: 'border-emerald-500/30 bg-emerald-500/10 text-emerald-100',
+  warning: 'border-amber-500/30 bg-amber-500/10 text-amber-100',
+};
+
+const labelStyles: Record<CalloutVariant, string> = {
+  note: 'text-sky-300',
+  tip: 'text-emerald-300',
+  warning: 'text-amber-300',
+};
+
+export const TldrBlock: React.FC<{ items: string[] }> = ({ items }) => (
+  <section className="rounded-xl border border-cyan-500/25 bg-cyan-500/10 p-4">
+    <p className="text-xs font-semibold uppercase tracking-wider text-cyan-300">TL;DR</p>
+    <ul className="mt-2 space-y-1 text-sm text-cyan-100">
+      {items.map((item) => (
+        <li key={item}>- {item}</li>
+      ))}
+    </ul>
+  </section>
+);
+
+export const Callout: React.FC<{
+  variant: CalloutVariant;
+  title: string;
+  children: React.ReactNode;
+}> = ({ variant, title, children }) => (
+  <section className={`rounded-xl border p-4 ${calloutStyles[variant]}`}>
+    <p className={`text-xs font-semibold uppercase tracking-wider ${labelStyles[variant]}`}>{title}</p>
+    <div className="mt-2 text-sm leading-relaxed">{children}</div>
+  </section>
+);
+
+export const StepList: React.FC<{ steps: Array<{ title: string; detail: string }> }> = ({ steps }) => (
+  <ol className="space-y-3">
+    {steps.map((step, index) => (
+      <li key={step.title} className="flex gap-3 rounded-lg border border-slate-800/80 bg-slate-900/40 p-3">
+        <span className="mt-0.5 inline-flex h-6 w-6 shrink-0 items-center justify-center rounded-full border border-cyan-500/30 bg-cyan-500/10 text-xs font-semibold text-cyan-300">
+          {index + 1}
+        </span>
+        <div>
+          <p className="text-sm font-medium text-white">{step.title}</p>
+          <p className="mt-0.5 text-sm text-slate-400">{step.detail}</p>
+        </div>
+      </li>
+    ))}
+  </ol>
+);

src/components/DocsBlocks.tsx

@@ -1,5 +1,27 @@
-import React, { useState } from 'react';
+import React, { useEffect, useState } from 'react';
 import { NavLink, useLocation } from 'react-router-dom';
+import hljs from 'highlight.js/lib/core';
+import bash from 'highlight.js/lib/languages/bash';
+import dockerfile from 'highlight.js/lib/languages/dockerfile';
+import ini from 'highlight.js/lib/languages/ini';
+import javascript from 'highlight.js/lib/languages/javascript';
+import json from 'highlight.js/lib/languages/json';
+import powershell from 'highlight.js/lib/languages/powershell';
+import python from 'highlight.js/lib/languages/python';
+import typescript from 'highlight.js/lib/languages/typescript';
+import xml from 'highlight.js/lib/languages/xml';
+import yaml from 'highlight.js/lib/languages/yaml';
+
+hljs.registerLanguage('bash', bash);
+hljs.registerLanguage('dockerfile', dockerfile);
+hljs.registerLanguage('ini', ini);
+hljs.registerLanguage('javascript', javascript);
+hljs.registerLanguage('json', json);
+hljs.registerLanguage('powershell', powershell);
+hljs.registerLanguage('python', python);
+hljs.registerLanguage('typescript', typescript);
+hljs.registerLanguage('xml', xml);
+hljs.registerLanguage('yaml', yaml);
 
 interface SidebarSection {
   title: string;
@@ -9,7 +31,7 @@ interface SidebarSection {
 
 const sections: SidebarSection[] = [
   {
-    title: 'Getting Started',
+    title: 'Nihil Wrapper',
     icon: (
       <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
         <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M15.59 14.37a6 6 0 01-5.84 7.38v-4.8m5.84-2.58a14.98 14.98 0 006.16-12.12A14.98 14.98 0 009.63 8.41m5.96 5.96a14.926 14.926 0 01-5.84 2.58m0 0a14.926 14.926 0 01-5.84-2.58" />
@@ -19,33 +41,27 @@ const sections: SidebarSection[] = [
       { label: 'Linux', to: '/docs/installation/linux' },
       { label: 'macOS', to: '/docs/installation/macos' },
       { label: 'Windows', to: '/docs/installation/windows' },
-    ],
-  },
-  {
-    title: 'Usage',
-    icon: (
-      <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M6.75 7.5l3 2.25-3 2.25m4.5 0h3m-9 8.25h13.5A2.25 2.25 0 0021 18V6a2.25 2.25 0 00-2.25-2.25H5.25A2.25 2.25 0 003 6v12a2.25 2.25 0 002.25 2.25z" />
-      </svg>
-    ),
-    items: [
       { label: 'CLI Commands', to: '/docs/usage' },
       { label: 'Configuration', to: '/docs/configuration' },
+      { label: 'Services', to: '/docs/service' },
+      { label: 'Shell Completion', to: '/docs/completion' },
+      { label: 'Command History', to: '/docs/history' },
     ],
   },
   {
-    title: 'Images',
+    title: 'Nihil Images',
     icon: (
       <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M21 7.5l-2.25-1.313M21 7.5v2.25m0-2.25l-2.25 1.313M3 7.5l2.25-1.313M3 7.5l2.25 1.313M3 7.5v2.25m9 3l2.25-1.313M12 12.75l-2.25-1.313M12 12.75V15m0 6.75l2.25-1.313M12 21.75V19.5m0 2.25l-2.25-1.313m0-16.875L12 2.25l2.25 1.313M21 14.25v2.25l-2.25 1.313m-13.5 0L3 16.5v-2.25" />
+        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M6.75 7.5l3 2.25-3 2.25m4.5 0h3m-9 8.25h13.5A2.25 2.25 0 0021 18V6a2.25 2.25 0 00-2.25-2.25H5.25A2.25 2.25 0 003 6v12a2.25 2.25 0 002.25 2.25z" />
       </svg>
     ),
     items: [
       { label: 'Available Images', to: '/docs/images' },
+      { label: 'Architecture', to: '/docs/architecture' },
     ],
   },
   {
-    title: 'nihil-history',
+    title: 'Nihil History',
     icon: (
       <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
         <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M12 6v6h4.5m4.5 0a9 9 0 11-18 0 9 9 0 0118 0z" />
@@ -56,39 +72,16 @@ const sections: SidebarSection[] = [
     ],
   },
   {
-    title: 'Features',
-    icon: (
-      <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M9.813 15.904L9 18.75l-.813-2.846a4.5 4.5 0 00-3.09-3.09L2.25 12l2.846-.813a4.5 4.5 0 003.09-3.09L9 5.25l.813 2.846a4.5 4.5 0 003.09 3.09L15.75 12l-2.846.813a4.5 4.5 0 00-3.09 3.09z" />
-      </svg>
-    ),
-    items: [
-      { label: 'Shell Completion', to: '/docs/completion' },
-      { label: 'Command History', to: '/docs/history' },
-    ],
-  },
-  {
-    title: 'Project',
+    title: 'About',
     icon: (
       <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
         <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M2.25 12.75V12A2.25 2.25 0 014.5 9.75h15A2.25 2.25 0 0121.75 12v.75m-8.69-6.44l-2.12-2.12a1.5 1.5 0 00-1.061-.44H4.5A2.25 2.25 0 002.25 6v12a2.25 2.25 0 002.25 2.25h15A2.25 2.25 0 0021.75 18V9a2.25 2.25 0 00-2.25-2.25h-5.379a1.5 1.5 0 01-1.06-.44z" />
       </svg>
     ),
     items: [
-      { label: 'Architecture', to: '/docs/architecture' },
-      { label: 'Contributing', to: '/docs/contributing' },
-    ],
-  },
-  {
-    title: 'More',
-    icon: (
-      <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M8.625 12a.375.375 0 11-.75 0 .375.375 0 01.75 0zm0 0H8.25m4.125 0a.375.375 0 11-.75 0 .375.375 0 01.75 0zm0 0H12m4.125 0a.375.375 0 11-.75 0 .375.375 0 01.75 0zm0 0h-.375M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
-      </svg>
-    ),
-    items: [
+      { label: 'About Nihil', to: '/docs/about' },
       { label: 'FAQ', to: '/docs/faq' },
-      { label: 'About', to: '/docs/about' },
+      { label: 'Contributing', to: '/docs/contributing' },
     ],
   },
 ];
@@ -154,6 +147,118 @@ export const DocsLayout: React.FC<{ children: React.ReactNode }> = ({ children }
   const isInSection = (section: SidebarSection) =>
     section.items.some((item) => location.pathname === item.to);
 
+  useEffect(() => {
+    const candidates = ['bash', 'powershell', 'json', 'yaml', 'python', 'xml', 'javascript', 'typescript', 'ini', 'dockerfile'];
+    const commandLineRe = /^\s*(\$|#)?\s*[a-zA-Z0-9_.-]+(?:\s+[-][-\w]+|\s+[A-Za-z0-9_./~:@'"=+-]+)*\s*$/;
+    const terminalPrefixes = ['nihil ', 'nhi ', 'nxh ', 'docker ', 'git ', 'pip ', 'pipx ', 'python ', 'npm ', 'pnpm ', 'yarn ', 'curl ', 'wget ', 'sudo '];
+    const looksLikeTerminal = (text: string) => {
+      const lines = text
+        .split('\n')
+        .map((line) => line.trim())
+        .filter(Boolean);
+      if (!lines.length) return false;
+      const matches = lines.filter((line) => {
+        const lower = line.toLowerCase();
+        if (lower.startsWith('#')) return true;
+        if (terminalPrefixes.some((prefix) => lower.startsWith(prefix))) return true;
+        return commandLineRe.test(line);
+      }).length;
+      return matches / lines.length >= 0.6;
+    };
+    const escapeHtml = (value: string) =>
+      value
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;');
+    const renderTerminalHtml = (text: string) => {
+      const lines = text.split('\n');
+      return lines
+        .map((rawLine) => {
+          const line = rawLine.trim();
+          if (!line) return '<span class="cmd-line"></span>';
+          if (line.startsWith('#')) {
+            return `<span class="cmd-comment">${escapeHtml(rawLine)}</span>`;
+          }
+          const tokens = line.split(/\s+/);
+          let prompt = '';
+          let command = tokens[0] ?? '';
+          let rest = tokens.slice(1);
+          if ((command === '$' || command === '#') && tokens.length > 1) {
+            prompt = command;
+            command = tokens[1];
+            rest = tokens.slice(2);
+          }
+          const promptPart = prompt
+            ? `<span class="cmd-prompt">${escapeHtml(prompt)}</span> `
+            : '';
+          const commandPart = `<span class="cmd-bin">${escapeHtml(command)}</span>`;
+          const argsPart = rest.length
+            ? ` <span class="cmd-args">${escapeHtml(rest.join(' '))}</span>`
+            : '';
+          return `<span class="cmd-line">${promptPart}${commandPart}${argsPart}</span>`;
+        })
+        .join('');
+    };
+
+    const blocks = document.querySelectorAll('.docs-content pre');
+    blocks.forEach((pre) => {
+      if (pre.dataset.enhanced === '1') return;
+      pre.dataset.enhanced = '1';
+
+      let code = pre.querySelector('code');
+      if (!code) {
+        code = document.createElement('code');
+        code.textContent = pre.textContent ?? '';
+        pre.textContent = '';
+        pre.appendChild(code);
+      }
+
+      const source = code.textContent ?? '';
+      const isTerminal = looksLikeTerminal(source);
+      const highlighted = isTerminal
+        ? { value: renderTerminalHtml(source) }
+        : hljs.highlightAuto(source, candidates);
+      const language = isTerminal ? 'shell' : (highlighted.language ?? 'text');
+      code.innerHTML = highlighted.value;
+      code.classList.add('hljs', `language-${language}`);
+
+      const wrapper = document.createElement('div');
+      wrapper.className = 'code-shell';
+      pre.parentNode?.insertBefore(wrapper, pre);
+      wrapper.appendChild(pre);
+
+      const header = document.createElement('div');
+      header.className = 'code-shell-head';
+
+      const label = document.createElement('span');
+      label.className = 'code-shell-lang';
+      label.textContent = language;
+
+      const button = document.createElement('button');
+      button.type = 'button';
+      button.className = 'code-shell-copy';
+      button.textContent = 'Copy';
+      button.onclick = async () => {
+        try {
+          await navigator.clipboard.writeText(source);
+          button.textContent = 'Copied';
+          window.setTimeout(() => {
+            button.textContent = 'Copy';
+          }, 1200);
+        } catch {
+          button.textContent = 'Error';
+          window.setTimeout(() => {
+            button.textContent = 'Copy';
+          }, 1200);
+        }
+      };
+
+      header.append(label, button);
+      wrapper.prepend(header);
+      pre.classList.add('code-shell-pre');
+    });
+  }, [location.pathname]);
+
   return (
     <div className="flex gap-12 items-start">
       <aside className="w-60 shrink-0 sticky top-24 hidden md:block">
@@ -170,7 +275,7 @@ export const DocsLayout: React.FC<{ children: React.ReactNode }> = ({ children }
           ))}
         </div>
       </aside>
-      <div className="flex-1 min-w-0">{children}</div>
+      <div className="flex-1 min-w-0 docs-content">{children}</div>
     </div>
   );
 };

src/components/DocsLayout.tsx

@@ -15,6 +15,7 @@ const ROUTE_META: Array<{ match: (p: string) => boolean; meta: MetaConfig }> = [
   { match: (p) => p === '/docs/nihil-history', meta: { title: 'TheNullPigeons - nihil-history', description: 'Track credentials, hosts, and access links across engagements.' } },
   { match: (p) => p === '/docs/architecture', meta: { title: 'TheNullPigeons - Architecture', description: 'Understand how nihil CLI, Docker manager, and image pipeline fit together.' } },
   { match: (p) => p === '/docs/configuration', meta: { title: 'TheNullPigeons - Configuration', description: 'Configure nihil paths, resources, env variables, and command history.' } },
+  { match: (p) => p === '/docs/service', meta: { title: 'TheNullPigeons - Services', description: 'Understand session services in nihil, including Desktop Browser UI and port behavior.' } },
   { match: (p) => p === '/docs/contributing', meta: { title: 'TheNullPigeons - Contributing', description: 'Report bugs, request tools, and contribute to the nihil ecosystem.' } },
   { match: (p) => p === '/docs/faq', meta: { title: 'TheNullPigeons - FAQ', description: 'Answers to frequent questions about nihil setup and usage.' } },
   { match: (p) => p === '/docs/about', meta: { title: 'TheNullPigeons - About', description: 'Why nihil was built and how the project is structured.' } },

src/components/SeoMeta.tsx

@@ -20,6 +20,7 @@ import { NihilHistoryPage } from './docs/NihilHistoryPage';
 import { ArchitecturePage } from './docs/ArchitecturePage';
 import { ConfigurationPage } from './docs/ConfigurationPage';
 import { ContributingPage } from './docs/ContributingPage';
+import { ServicePage } from './docs/ServicePage';
 import { BlogPage } from './BlogPage';
 import { BlogPostPage } from './BlogPostPage';
 import { SourceCodePage } from './SourceCodePage';
@@ -83,6 +84,10 @@ export const App: React.FC = () => {
           path="/docs/configuration"
           element={<DocsLayout><ConfigurationPage /></DocsLayout>}
         />
+        <Route
+          path="/docs/service"
+          element={<DocsLayout><ServicePage /></DocsLayout>}
+        />
         <Route
           path="/docs/contributing"
           element={<DocsLayout><ContributingPage /></DocsLayout>}