flowdeck/app/templates/help.html

{% extends "base.html" %}
{% block page_title %}Help{% endblock %}
{% block title_prefix %}Help{% endblock %}
{% block page_icon %}{{ fd_icon("help-circle",18) }}{% endblock %}

{% block topbar %}
{% set page_icon = "help-circle" %}
{% set page_title = "Help" %}
{% include '_header.html' %}
{% endblock %}

{% block content %}
{# Same panel skeleton as settings (shared /static/css/settings.css) #}
<style>
.help-body{margin-bottom:24px;max-width:760px;}
.help-body p{font-size:14px;color:var(--text-secondary);line-height:1.65;margin:0 0 10px;}
.help-body ul{margin:0 0 14px;padding-left:18px;}
.help-body li{font-size:14px;color:var(--text-secondary);line-height:1.6;margin-bottom:4px;}
.help-body code{background:var(--bg-tertiary);border:1px solid var(--border);border-radius:4px;padding:1px 6px;font-size:12.5px;}
.help-body h3{font-size:13px;text-transform:uppercase;letter-spacing:.5px;color:var(--text-dim);margin:22px 0 8px;padding-bottom:4px;border-bottom:1px solid var(--border);}
.help-kbd{display:inline-block;padding:2px 8px;background:var(--bg-tertiary);border:1px solid var(--border);border-radius:4px;font-family:monospace;font-size:12px;color:var(--text);min-width:16px;text-align:center;}
.help-shortcut-row{display:flex;align-items:center;gap:12px;padding:8px 12px;border-radius:6px;margin-bottom:2px;}
.help-shortcut-row:hover{background:var(--bg-hover);}
.help-shortcut-row .keys{display:flex;gap:4px;min-width:140px;}
.help-shortcut-row .desc{font-size:13px;color:var(--text-dim);}
.help-badge{display:inline-block;padding:2px 10px;border-radius:20px;font-size:11px;font-weight:600;}
.help-badge.local{background:rgba(35,131,226,.15);color:#2C8CEB;}
.help-badge.gitea{background:rgba(0,200,100,.15);color:#00CC66;}
.help-badge.github{background:rgba(130,80,220,.15);color:#A060F0;}
.help-badge.sso{background:rgba(217,115,13,.18);color:#E0952B;}
</style>

<div class="settings-overlay" x-data="helpInit()" style="background:none;backdrop-filter:none;position:static;z-index:1;padding:0;">
  <div class="settings-panel" style="width:100%;max-width:1050px;height:calc(100vh - 120px);margin:0 auto;" @keydown.escape="navOpen = false">
    <button class="settings-menu-btn" @click="navOpen = !navOpen" title="Sections" aria-label="Open sections menu">
      <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><line x1="3" y1="6" x2="21" y2="6"/><line x1="3" y1="12" x2="21" y2="12"/><line x1="3" y1="18" x2="21" y2="18"/></svg>
    </button>
    <button class="settings-close" @click="close()" title="Close" aria-label="Close help">×</button>

    <!-- Mobile drawer backdrop -->
    <div class="settings-nav-backdrop" x-show="navOpen" x-cloak @click="navOpen = false"></div>

    <!-- Left navigation -->
    <div class="settings-nav" :class="{ 'nav-open': navOpen }" @click.capture="closeNavOnMobile()">
      <div class="settings-nav-header">Basics</div>
      <div class="settings-nav-item" :class="{ active: section==='start' }" @click="go('start')">🚀 Getting Started</div>
      <div class="settings-nav-item" :class="{ active: section==='editor' }" @click="go('editor')">📝 Pages &amp; Editor</div>
      <div class="settings-nav-item" :class="{ active: section==='databases' }" @click="go('databases')">🗄️ Databases &amp; Views</div>
      <div class="settings-nav-item" :class="{ active: section==='tasks' }" @click="go('tasks')">✅ Tasks &amp; Dependencies</div>
      <div class="settings-nav-header">Workspace</div>
      <div class="settings-nav-item" :class="{ active: section==='workspaces' }" @click="go('workspaces')">📁 Workspaces &amp; Forges</div>
      <div class="settings-nav-item" :class="{ active: section==='collab' }" @click="go('collab')">👥 Collaboration</div>
      <div class="settings-nav-item" :class="{ active: section==='nav' }" @click="go('nav')">📚 Library, Trash &amp; Search</div>
      <div class="settings-nav-header">Features</div>
      <div class="settings-nav-item" :class="{ active: section==='agent' }" @click="go('agent')">🤖 AI Agent &amp; Automations</div>
      <div class="settings-nav-item" :class="{ active: section==='integrations' }" @click="go('integrations')">🔌 Integrations &amp; API</div>
      <div class="settings-nav-item" :class="{ active: section==='pwa' }" @click="go('pwa')">📶 Offline &amp; PWA</div>
      <div class="settings-nav-item" :class="{ active: section==='auth' }" @click="go('auth')">🔐 Accounts &amp; SSO</div>
      <div class="settings-nav-header">Reference</div>
      <div class="settings-nav-item" :class="{ active: section==='shortcuts' }" @click="go('shortcuts')">⌨️ Keyboard Shortcuts</div>
      <div class="settings-nav-item" :class="{ active: section==='tips' }" @click="go('tips')">💡 Tips</div>
    </div>

    <!-- Content -->
    <div class="settings-content">

      <div class="help-body" x-show="section==='start'">
        <h2>Getting Started</h2>
        <p>FlowDeck is your private, self-hosted Notion-style workspace — pages, databases, and Git-forge (Gitea / GitHub) integration in one app.</p>
        <h3>First steps</h3>
        <ul>
          <li>Open <b>Workspaces</b> (<code>/workspaces</code>) to pick or create a workspace — local or connected to a forge.</li>
          <li>Click <b>+ New page</b> in the sidebar to start writing, or press <span class="help-kbd">Ctrl</span>+<span class="help-kbd">N</span>.</li>
          <li>Use the <b>Agent &amp; IA</b> section in Settings to plug an LLM provider (OpenAI, Ollama, DeepInfra…) if you want AI features.</li>
        </ul>
        <h3>The sidebar</h3>
        <ul>
          <li>The workspace header (top-left) switches workspaces and opens your account menu.</li>
          <li>Tabs <b>Home / Chat / Meetings / Inbox</b> swap the sidebar content; pages are a drag-and-drop tree.</li>
          <li>On mobile the sidebar is a drawer: open it with the hamburger button, close it by tapping outside or swiping left.</li>
        </ul>
      </div>

      <div class="help-body" x-show="section==='editor'">
        <h2>Pages &amp; Editor</h2>
        <p>Notion-style block editor: every line is a block you can drag, convert, and nest.</p>
        <h3>Blocks</h3>
        <ul>
          <li>Type <code>/</code> for the slash menu — headings, callouts, toggles, code, math (KaTeX), tables, images, embeds, ToC…</li>
          <li>Markdown shortcuts as you type: <code># </code> heading, <code>- </code> bullet, <code>1. </code> numbered, <code>&gt; </code> quote, <code>[] </code> todo, <code>``` </code> code.</li>
          <li>Drag the handle left of a block to move or nest it; <span class="help-kbd">Tab</span>/<span class="help-kbd">Shift+Tab</span> indent/outdent.</li>
          <li>Inline formatting: bold, italic, code, links, colors via the selection toolbar.</li>
        </ul>
        <h3>Page features</h3>
        <ul>
          <li>Cover image and icon on every page (click the top of the page).</li>
          <li>Inline databases: add a table/board/calendar collection directly in a page.</li>
          <li>Comments (threaded), page history with snapshots, backlinks.</li>
          <li>Right-click any sidebar item for context menu: duplicate, rename, move, delete.</li>
        </ul>
      </div>

      <div class="help-body" x-show="section==='databases'">
        <h2>Databases &amp; Views</h2>
        <p>Collections are databases with a JSON schema, independent of Gitea. <b>21 property types</b>: title, text, number, select, multi-select, status, date, person, checkbox, url, email, phone, files, unique_id, relation, rollup, formula, and auto-properties.</p>
        <h3>Views</h3>
        <ul>
          <li><b>Table</b> — sortable columns, inline editing.</li>
          <li><b>Board (Kanban)</b> — group by select/status, drag &amp; drop between columns.</li>
          <li><b>Calendar</b> — month grid by date property.</li>
          <li><b>Gallery</b> — visual cards, configurable card size.</li>
          <li><b>List</b> — compact rows with preview.</li>
          <li><b>Timeline</b> — Gantt bars from date ranges.</li>
          <li><b>Status Overview / Team Load</b> — donut + stacked-bar dashboards.</li>
        </ul>
        <h3>Relations, rollups, formulas</h3>
        <ul>
          <li>Relations are bidirectional: link rows across collections.</li>
          <li>Rollups aggregate related rows (12 aggregations: sum, count, average, min, max…).</li>
          <li>Formulas support 19 functions over row properties.</li>
          <li>Filters, sorts and grouping apply per-view.</li>
        </ul>
      </div>

      <div class="help-body" x-show="section==='tasks'">
        <h2>Tasks &amp; Dependencies</h2>
        <ul>
          <li>Todo blocks anywhere in pages become checkboxes; the <b>My Tasks</b> page aggregates every task in every collection you can access.</li>
          <li>My Tasks views: <b>All / Today / Overdue / Next 7 days</b>.</li>
          <li><b>Sub-items</b>: unlimited hierarchy — a parent row is Done when all children are Done (status aggregate).</li>
          <li><b>Dependencies</b>: Blocking / Blocked by between rows; transitioning a blocked task is refused until its blocker is done.</li>
        </ul>
      </div>

      <div class="help-body" x-show="section==='workspaces'">
        <h2>Workspaces &amp; Forges</h2>
        <p>Organize work into separate workspaces, each with its own page tree, collections and members.</p>
        <ul>
          <li><span class="help-badge local">Local</span> Pages and files stored on your server (SQLite under <code>/data</code>).</li>
          <li><span class="help-badge gitea">Gitea</span> Connect your Gitea account (Settings → Integrations): repos appear as workspaces, browse the file tree in the sidebar, create/edit files with commit messages, sync labels as tags.</li>
          <li><span class="help-badge github">GitHub</span> Connect via Settings → Integrations for repo browsing.</li>
          <li>Gitea legacy boards are auto-adapted into FlowDeck collections (GiteaBoardCompat).</li>
          <li>The <b>Private</b> section appears when a remote workspace is active — those pages stay local.</li>
        </ul>
      </div>

      <div class="help-body" x-show="section==='collab'">
        <h2>Collaboration</h2>
        <ul>
          <li><b>Roles</b>: workspace members are admin / editor / commenter / viewer.</li>
          <li><b>Sharing</b>: the Share button (top-right of a page) — share with specific users or publish a read-only public link (<code>/p/your-slug</code>).</li>
          <li><b>Teamspaces</b> (wiki): shared knowledge spaces with their own pages.</li>
          <li><b>Meetings</b>: meeting notes with an action-items panel.</li>
          <li><b>Sprints</b>: time-box collections of tasks, with burndown-ready statuses.</li>
          <li><b>Notifications</b>: bell in the topbar for mentions, assignments, comments.</li>
          <li>Live editing: changes propagate to other open tabs (real-time sync).</li>
        </ul>
      </div>

      <div class="help-body" x-show="section==='nav'">
        <h2>Library, Trash &amp; Search</h2>
        <ul>
          <li><b>Library</b> (<code>/library</code>) — tabs for Recents, Favorites, Shared, Published, with filtering.</li>
          <li><b>Trash</b> (<code>/trash</code>) — soft-deleted pages, 30-day retention, restore or purge.</li>
          <li><b>Ctrl+K</b> — command palette: fuzzy search across pages, jump anywhere, start an AI answer.</li>
          <li>Full-text search API: <code>/api/v2/search</code>.</li>
        </ul>
      </div>

      <div class="help-body" x-show="section==='agent'">
        <h2>AI Agent &amp; Automations</h2>
        <ul>
          <li><b>Chat sidebar</b> (Chat tab): conversations with your configured LLM; pages can be attached as context.</li>
          <li><b>Agent panel</b> on pages: propose edits, generate content, answer questions about the workspace.</li>
          <li><b>Skill marketplace</b>: export/import portable skills, install presets from the <code>/</code> gallery.</li>
          <li><b>Automations</b> (Settings → Automations): visual pipeline of trigger → condition → delay → action (webhook, notification, page update…), with run history and legacy JSON conversion.</li>
          <li>Configure providers in <b>Settings → Agent &amp; IA</b>: per-provider API keys, model lists, offline mode without any provider.</li>
        </ul>
      </div>

      <div class="help-body" x-show="section==='integrations'">
        <h2>Integrations &amp; API</h2>
        <ul>
          <li><b>Public API v2</b> — <code>/api/v2</code>: CRUD on collections, pages, properties, views, comments, notifications, favorites, tags, sharing, sprints, templates. Bearer tokens (Settings → API tokens) with scopes <code>read</code>/<code>write</code>/<code>admin</code>, pagination, filters, sorting, idempotency keys, RFC 7807 errors. Interactive docs at <a href="/docs" target="_blank" rel="noopener">/docs</a>.</li>
          <li><b>Agent API</b> — <code>/api/v2/agents/*</code>: agents, conversations, synchronous JSON run, action journal with rollback, external trigger.</li>
          <li><b>Webhooks</b>: outgoing events (create/update/delete) managed in Settings → Integrations; incoming Gitea webhooks keep boards in sync.</li>
          <li><b>Web Clipper</b> — browser extension (Manifest V3): clip article / selection / bookmark / screenshot straight into FlowDeck.</li>
          <li><b>Import / Export</b>: CSV import, JSON/CSV/Markdown export.</li>
        </ul>
      </div>

      <div class="help-body" x-show="section==='pwa'">
        <h2>Offline mode (PWA)</h2>
        <p>FlowDeck is a Progressive Web App: pages you visited stay available offline and your edits are saved locally, then synchronised when the connection returns.</p>
        <ul>
          <li><b>Install:</b> browser menu → <i>Install app</i> (Chrome/Edge) or <i>Add to Home Screen</i> (Safari/iOS).</li>
          <li><b>Offline editing:</b> while offline, the editor stores changes in the browser (IndexedDB) and shows an offline banner with the number of pending changes. A ⟳ icon marks pages with unsynced edits.</li>
          <li><b>Reconnection:</b> the queue is replayed automatically (and via Background Sync); a spinner badge appears while syncing, then a confirmation toast.</li>
          <li><b>Conflicts:</b> the latest edit wins with a notice; server-side-deleted pages are recreated as orphan pages; title collisions get an <i>“…(copie offline)”</i> suffix.</li>
        </ul>
      </div>

      <div class="help-body" x-show="section==='auth'">
        <h2>Accounts &amp; SSO</h2>
        <p>
          <span class="help-badge local">Local</span> Email + password — create an account on the login page.<br><br>
          <span class="help-badge gitea">Gitea OAuth</span> / <span class="help-badge github">GitHub OAuth</span> — sign in with your forge; your repos become workspaces. You can link a forge to an existing local account — your identity stays local.<br><br>
          <span class="help-badge sso">SSO</span> <b>Enterprise SSO</b> — in <b>Settings → Admin → SSO / Enterprise</b>:
        </p>
        <ul>
          <li><b>SAML 2.0</b> — paste IdP Entity ID, SSO URL and signing certificate; give the IdP your <code>/auth/saml/metadata</code> link.</li>
          <li><b>OpenID Connect</b> — Issuer URL, Client ID and Client Secret (PKCE, scopes <code>openid profile email</code>).</li>
          <li>Just-in-time provisioning, IdP groups mapped to workspace roles, <i>SSO only</i> mode disables local login (admins keep their door). Every attempt is audited in the login history.</li>
        </ul>
        <p>Sessions and API tokens are managed in Settings → Sessions / API tokens.</p>
      </div>

      <div class="help-body" x-show="section==='shortcuts'">
        <h2>Keyboard Shortcuts</h2>
        <div class="help-shortcut-row"><div class="keys"><span class="help-kbd">Ctrl</span>+<span class="help-kbd">K</span></div><div class="desc">Command palette / quick find</div></div>
        <div class="help-shortcut-row"><div class="keys"><span class="help-kbd">Ctrl</span>+<span class="help-kbd">N</span></div><div class="desc">Create new page</div></div>
        <div class="help-shortcut-row"><div class="keys"><span class="help-kbd">Ctrl</span>+<span class="help-kbd">S</span></div><div class="desc">Save current page</div></div>
        <div class="help-shortcut-row"><div class="keys"><span class="help-kbd">Ctrl</span>+<span class="help-kbd">O</span></div><div class="desc">New AI chat (footer)</div></div>
        <div class="help-shortcut-row"><div class="keys"><span class="help-kbd">/</span></div><div class="desc">Slash command menu (in editor)</div></div>
        <div class="help-shortcut-row"><div class="keys"><span class="help-kbd">F2</span></div><div class="desc">Rename selected item</div></div>
        <div class="help-shortcut-row"><div class="keys"><span class="help-kbd">Delete</span></div><div class="desc">Move selected item to trash</div></div>
        <div class="help-shortcut-row"><div class="keys"><span class="help-kbd">Enter</span></div><div class="desc">Open selected page</div></div>
        <div class="help-shortcut-row"><div class="keys"><span class="help-kbd">Tab</span> / <span class="help-kbd">Shift</span>+<span class="help-kbd">Tab</span></div><div class="desc">Indent / outdent block</div></div>
        <div class="help-shortcut-row"><div class="keys"><span class="help-kbd">Escape</span></div><div class="desc">Close modal / cancel editing</div></div>
      </div>

      <div class="help-body" x-show="section==='tips'">
        <h2>Tips</h2>
        <ul>
          <li>Toggle the desktop sidebar with the « button; collapsed, hover the left edge to peek it.</li>
          <li><b>Ctrl+Click</b> / <b>Shift+Click</b> multi-select in the sidebar tree.</li>
          <li>Hover any sidebar item for quick actions (favorite, share, delete).</li>
          <li>Drag pages into the tree to reorganize; drop onto a page to nest it.</li>
          <li>The section <b>⋮</b> menus reorder or hide sidebar sections to taste.</li>
          <li>Dark/light theme toggle is in the topbar and persists across reloads.</li>
        </ul>
      </div>

    </div>
  </div>
</div>

<script data-cfasync="false" src="/static/js/help.js?v={{ asset_version }}"></script>
{% endblock %}