@nightkatana/kronosys-app 1.0.0-beta.0

package/lib/userGuideCopy.ts

@@ -0,0 +1,464 @@
+import type { Lang } from "./dashboardCopy";
+
+export type UserGuideSection = {
+  id: string;
+  title: string;
+  /** Intro humaine +, si besoin, une phrase de transition vers le concret. */
+  paragraphs: string[];
+  /**
+   * Étapes numérotées (enchainement dans l’interface) — mélange *pourquoi / comment*.
+   * Précéder souvent d’un premier paragraphe qui donne l’intention.
+   */
+  steps?: string[];
+  /** Sous-titre du bloc d’étapes (sinon le libellé par défaut du bundle). */
+  stepsTitle?: string;
+  /** Listes d’**options** ou *cas d’usage* (choix, modes, onglets). */
+  options?: string[];
+  /** Sous-titre du bloc options (sinon le libellé par défaut du bundle). */
+  optionsTitle?: string;
+  /** Puces courtes (rappels, raccourcis, conflits). */
+  bullets?: string[];
+  /** Texte interne pour le filtre de recherche (mots-clés en plus du titre et des paragraphes). */
+  searchIndex: string;
+};
+
+export type UserGuideBundle = {
+  pageTitle: string;
+  pageSubtitle: string;
+  /** Titre de section par défaut au-dessus des listes `steps` si `stepsTitle` est omis. */
+  defaultStepBlockTitle: string;
+  /** Titre de section par défaut au-dessus des `options` si `optionsTitle` est omis. */
+  defaultOptionsBlockTitle: string;
+  searchPlaceholder: string;
+  searchAriaLabel: string;
+  searchNoResults: string;
+  tocHeading: string;
+  tocNavAria: string;
+  lastUpdated: string;
+  sections: UserGuideSection[];
+};
+
+function frBundle(): UserGuideBundle {
+  return {
+    pageTitle: "Guide d’utilisation",
+    pageSubtitle:
+      "Chaque rubrique mélange **l’intention** (à quoi ça sert *pour vous*), des **étapes** quand c’est enchainé à l’écran, et des **options** concrètes — le tout dans le **même thème** clair ou sombre que l’appli.",
+    defaultStepBlockTitle: "Procédure (pas à pas dans l’interface)",
+    defaultOptionsBlockTitle: "Options, modes et rappels",
+    searchPlaceholder: "Filtrer les rubriques (sens, étapes, options, KronoFocus…)",
+    searchAriaLabel: "Recherche dans le guide",
+    searchNoResults: "Aucune rubrique ne correspond à votre recherche. Essayez un autre mot-clé ou effacez le filtre.",
+    tocHeading: "Sur cette page",
+    tocNavAria: "Sommaire du guide d’utilisation",
+    lastUpdated: "Dernière mise à jour : avril 2026",
+    sections: [
+      {
+        id: "ug-essence",
+        title: "C’est quoi Kronosys — le sens, pas l’onglet",
+        searchIndex:
+          "but intention pourquoi aide bénéfice productivité focus temps mémoire concentration équipe client reconstituer oubli rythme travail vie attention local données chez soi",
+        paragraphs: [
+          "Kronosys, c’est un **compagnon** pour *temps* et *travail* : poser **ce** que vous faites, **combien** de temps, dans quel **sujet**, sans théâtre administratif. **À quoi ça sert ?** Moins d’amnésie sur *« j’y ai vraiment mis quoi, cette semaine ? »*, plus de **clôture** propre à la fin d’un bloc, un **récit** (pour vous, une équipe, un client) quand il le faut.",
+          "**Pour qui** est-ce pensé ? Les journées en **morceaux** (code, contenu, opérations, recherche…), les **contextes** qui s’entassent, ou le besoin d’**expliquer** sans tout refaire sur Excel. Kronosys reste *chez vous* côté données; Git, miroir, grosse sauvegarde, ce sont des **câbles** que l’on ajoute *quand vous voulez*.",
+        ],
+        optionsTitle: "Trois « pièces » pour trois gestes",
+        options: [
+          "**Tableau de bord** — l’*atelier* (sessions, tâches, minuteur, raccourcis d’**étiquettes** / **@projets**).",
+          "**Rapports** — le *regard en hauteur* (période, thèmes, graphiques, sans refabriquer les chiffres).",
+          "**Paramètres** — l’*arrière-boutique* (habitudes, raccordements, zone où l’on *efface* l’histoire *avec prudence*). [Ouvrir Paramètres](/settings#settings-usage-profile).",
+        ],
+        stepsTitle: "Premier contact en cinq pas (sans tout maîtriser le jour 1)",
+        steps: [
+          "Ouvrez l’**accueil** (tableau de bord) : c’est ici que démarre l’**atelier**.",
+          "Déclenchez **Nouvelle session** (ou laissez l’app en créer une *la première fois* qu’une tâche part).",
+          "Décrivez un **coup de tâche** (titre) ; un **#mot** = étiquette, un **@nom** = *projet* (le formulaire *devine* souvent l’un et l’autre).",
+          "Appuyez sur **Démarrer** (ou lancez le **KronoFocus** *à côté*) pour **tenir** un *créneau*.",
+          "Quand la journée le demande, ouvrez **Rapports** pour *voir* ce qui c’est *passé* dans la période — *sans* y passer la soirée en tableurs.",
+        ],
+      },
+      {
+        id: "ug-nav-theme",
+        title: "Barre d’outils, thème et langue",
+        searchIndex: "thème clair sombre mode violet zinc langue fr en",
+        paragraphs: [
+          "La **barre du haut** est *toujours* la même famille : mêmes outils, même **ton** (zinc, accents **violet**), pour ne pas recharger le cerveau *à chaque page*. L’icône **roue** mène à [Paramètres](/settings#settings-usage-profile) (raccourci **Alt+Shift+S** depuis le tableau de bord).",
+        ],
+        steps: [
+          "En **tableau de bord** : l’icône **Livre** mène ici, puis **Rapports** (graphe), **Paramètres** (roue).",
+          "Sur **les autres pages** : revenez à l’**accueil** (icône en **grille**), puis mêmes **Livre**, **Rapports**, **Paramètres** (et, sur **Licences** seule, l’icône **document**).",
+          "Le **bouton thème** bascule **clair / sombre** (le soir ou salle trop lumineuse).",
+          "Le bouton **actualiser** redemande l’**état** au serveur (utile si quelqu’un/quelque chose a changé dehors *sans* recharger toute l’**app**).",
+          "Ouvrez le **menu de langue** (FR / EN) ; la **préférence** peut se **mémoriser** côté moteur si c’est la configuration chez vous.",
+        ],
+        options: [
+          "**Livre** = ce **guide** ; **graphe** = **Rapports** ; **roue** = **Paramètres** ; **fichier** = **Licences** (cette dernière **seule** sur l’icône document).",
+          "Changer de **thème** ne modifie **pas** le **fond** de vos enregistrements — seulement le **confort** visuel (même **décor** d’écran d’une page à l’autre, pour ne pas se **perdre** entre les onglets)."
+        ],
+      },
+      {
+        id: "ug-layout",
+        title: "Où travailler, où regarder, où régler — + juridique",
+        searchIndex: "navigation tableaux bord rapports paramètres licences",
+        paragraphs: [
+          "Trois gestes, trois endroits : l’**atelier** (maintenant), les **Rapports** (retour sur une période), les **Paramètres** (coulisses, effacements sensibles, branchements). Puis **Licences**, la page d’honnêteté sur le code **open source** et les polices.",
+        ],
+        options: [
+          "**Tableau de bord** — à gauche la **file des sessions** ; au centre les **tâches** (minuteurs, détail) ; à droite les raccourcis d’**étiquettes** et **@projets** pour ne pas retaper les mêmes mots. C’est l’usage **quotidien**.",
+          "**Rapports** — choisir une **plage de dates** et, si besoin, des **#étiquettes** ; lire résumés et graphiques. Une **visite guidée** est proposée la première fois sur l’écran.",
+          "**Paramètres** — profil, collecte, planification, étiquettes avancées, **Git** ou miroir en **option** ; la **zone dangereuse** supprime l’historique (avec saisie de confirmation). [Sommaire des paramètres](/settings#settings-usage-profile) · [zone de danger](/settings#settings-danger-zone). N’y entrez **que** quand vous le **décidez**.",
+          "**Licences** — textes MIT, logiciels tiers, polices ; icône **document** **uniquement** sur cette page."
+        ],
+      },
+      {
+        id: "ug-sessions-tasks",
+        title: "Sessions, tâches, étiquettes et projets",
+        searchIndex: "session live archiver terminer tâche minuteur pause sous-tâche",
+        paragraphs: [
+          "La **session** est le **sac** où vient s’additionner le travail sur une période ; la **tâche** est le fil conducteur du moment. **#mot** = thème, **@nom** = projet (le formulaire en propose souvent) — c’est de la **classification**, pas un examen d’orthographe.",
+        ],
+        optionsTitle: "Nouvelle session — le cadre, au choix",
+        options: [
+          "**Portée minimale** : pas de bordage particulier — vous lancez et c’est le flux qui mène.",
+          "**Durée max (horloge murale)** : l’onglet s’y prête (rappel, pas alarme) quand on veut cadrer un gros **morceau** de journée.",
+          "**Fenêtre calendrier** : dates de **début** et de **fin** (engagement auprès de vous-même ou d’un tiers).",
+          "**Semaine** : jours de la semaine + **plage horaire** (utile en rythme **fixe** — pas pour tout le monde, et c’est normal).",
+          "Dans les sélecteurs de dates/heures, les actions rapides **Aujourd’hui** et/ou **Maintenant** sont disponibles pour éviter la saisie manuelle.",
+          "Les **tâches** se suivent en **direct** (minuteur) ou s’inscrivent **dans le passé** (début / fin explicites) : honnête quand on remplit **après coup** le soir, sans théâtre."
+        ],
+        stepsTitle: "Dès que vous avez cliqué « Démarrer » sur une tâche (ordre usuel)",
+        steps: [
+          "Taper un **titre** ; saupoudrer d’un **#** (étiquette) et/ou d’un **@** (projet) dès que le mot vient (aperçu souvent **sous** le champ de saisie).",
+          "Cliquer **Démarrer** sur la tâche — ou, si l’heure s’y prête, lancer d’**abord** le **KronoFocus** depuis cette tâche (même bateau, rythme différent).",
+          "Si le minuteur d’**une** autre tâche tourne déjà : l’appli offre **pause** sur l’ancienne, **terminer** l’ancienne, ou **tout** tenir en parallèle (vous **pouvez** mémoriser l’**option** pour les prochains lancements).",
+          "En **cours** : lister des **sous-tâches** ; les cocher, les reclasser au **glisser-déposer** ; **pause** / reprise en douceur.",
+          "**Terminer la session** quand le bloc a une fin (bouton d’en-tête ou bannière) ; une **raison** de clôture **facultative** (dans les temps, en avance, dépassement, autre + note) : pour poser mots sur la **fin** du cycle — d’**abord** pour vous, pas pour un **audit** froid."
+        ],
+        bullets: [
+          "L’**option** **Commit** à la fin d’une tâche, quand elle apparaît, concerne **Git** (voir [Synchronisation Git](/settings#settings-git) côté paramètres) : elle n’est **là** que **si** l’intégration est en place — les **équipiers** **non** devs peuvent l’**ignorer** sereinement."
+        ],
+      },
+      {
+        id: "ug-kronofocus",
+        title: "KronoFocus — retenir le rythme, pas un bulletin",
+        searchIndex: "pomodoro focus minuteur travail pause durée hh:mm",
+        paragraphs: [
+          "**Travail**, **pause**, **reprise**, **longue pause** : l’idée est l’**alternance** saine, pas une **note** sur le nombre de minutes. Proche d’un **pomodoro**, sans s’y figer si votre rythme diffère."
+        ],
+        optionsTitle: "Où c’est proposé, quoi cliquer",
+        options: [
+          "Section [KronoFocus (tableau de bord)](/settings#settings-kronoFocus) dans **Paramètres** : minuteur **dans l’en-tête** et/ou **près des actions de tâche** — cocher selon l’encombrement (le **profil** d’usage peut **masquer** d’autres blocs ailleurs).",
+          "Sur le **panneau** : **Démarrer**, **Pause**, reprise ; **durée** en `HH:MM:SS` ; **durée par défaut** (p. ex. 25 min) d’un clic ; **historique** des durées pour **réappliquer** la même mesure **sans** la retaper.",
+          "Lier le KronoFocus **à** la tâche **active** : utile pour **retrouver** dans l’historique **quelle** tâche portait ce **bloc** de focus."
+        ],
+        steps: [
+          "Ouvrez le KronoFocus (en-tête ou près d’une tâche) ; basculez **travail** / **pause** / **longue pause** selon l’**état** affiché.",
+          "Ajustez la **durée** (saisie ou raccourci) ; enregistrez souvent la **même** durée **dans l’historique** pour un **réemploi** en un clic.",
+          "Lancez le **décompte** ; en fin de phase, l’**écran** propose la **suite** (reprise, autre mode) selon le **flux** en cours."
+        ],
+      },
+      {
+        id: "ug-search-palette",
+        title: "Recherche : données (tableau de bord) & rubriques (ce guide)",
+        searchIndex: "palette recherche données sessions tâches ctrl k",
+        paragraphs: [
+          "Même **allure** de champ (bordure zinc, focus **violet**) : **deux cibles** — d’**abord** l’**atelier** (sessions, tâches, étiquettes, mots du workspace) ; **ensuite** le **fil** en tête de **cette** page, qui ne filtre **que** les **rubriques** du **guide**."
+        ],
+        stepsTitle: "Données — la palette (tableau de bord)",
+        steps: [
+          "Cliquer sur **Rechercher dans les données** ou presser **Ctrl+K** (Windows / Linux) / **⌘K** (macOS) : la **palette** s’ouvre (raccourci **réservé** : on ne le **redéfinit** **pas** dans la modale raccourcis).",
+          "Saisir **deux** ou **trois** **lettres** d’**une** **session**, d’**une** **tâche**, d’**un** **#** ou d’**un** **@** : la **liste** se **restreint** en **direct**.",
+          "Choisir **une** **ligne** (**Entrée** ou **clic**) : l’**écran** **saute** **vers** l’**objet** ; **Échap** **ferme** la **boîte** **sans** **toucher** le **fond**."
+        ],
+        optionsTitle: "Ce guide — le champ collé en haut de page",
+        options: [
+          "Il ne **lit** **pas** la **base** Kronosys : **seules** les **sections** de **ce** texte d’aide (titres + corps) **subissent** le **filtre**.",
+          "Le **compteur** `n / total` (à **droite** du **champ**) rappelle **combien** de **rubriques** **restent** **visibles** **après** la **saisie**."
+        ],
+      },
+      {
+        id: "ug-shortcuts",
+        title: "Raccourcis clavier (tableau de bord)",
+        searchIndex: "raccourcis clavier alt shift ctrl",
+        paragraphs: [
+          "Ouvrez la **modale des raccourcis** depuis le petit clavier près de la palette pour voir, **modifier** ou **réinitialiser** les combinaisons (les touches **Ctrl+K** / **⌘K** restent réservées à la palette de recherche de données). La relance de **certaines** visites guidées et des options d’**API** se gèrent aussi dans [Paramètres — Web & API](/settings#settings-web).",
+        ],
+        bullets: [
+          "Nouvelle session : Alt+Shift+N (par défaut).",
+          "Rapports : Alt+Shift+G · Paramètres : Alt+Shift+S · **Guide (cette app)** : Alt+Shift+U.",
+          "Colonnes : Ctrl+Alt+H (sessions) · J (tâches) · Y (étiquettes).",
+          "Thème : Alt+Shift+T · Langue : Alt+Shift+L · Terminer session live : Alt+Shift+E.",
+        ],
+      },
+      {
+        id: "ug-reporting",
+        title: "Rapports : la mémoire qui tient, quand on doit la raconter",
+        searchIndex: "agregats kpi plage date étiquette semaine assiduité retard heure planifiée",
+        paragraphs: [
+          "Les **rapports** ne jaugent pas votre humanité : ils aident à **répondre** à *est-ce qu’on peut, ensemble, s’y retrouver sur une période ?* Ce qui n’est **pas** **encore** fini reste **indiqué** (brouillon **honnête**, pas punition).",
+          "L’appli **agrège** ce que **vous** avez **déjà** posé (durées, tags, projets) ; parfois des **lignes** / **signaux** côté code et un **aperçu** de dossier **si** c’est **activé** chez vous. Une **visite** sur l’écran adoucit le **premier** tour.",
+          "Lorsque l’**hôte** d’enregistrement a **fourni** l’heure de **début prévue** à l’ouverture d’une session (p. ex. moteur lié à l’[horaire](/settings#settings-schedule) ou aux [sessions planifiées](/settings#settings-planned-sessions)), l’**écart** (retard ou avance) est **sauvegardé** sur la session et des **indicateurs d’assiduité** apparaissent dans le **résumé** des **Rapports** : ce n’est en général **pas** rempli par le seul bouton *Nouvelle session* du navigateur, sauf intégration explicite."
+        ],
+        stepsTitle: "Parcours type sur l’écran Rapports",
+        steps: [
+          "Ouvrir **Rapports** (icône **graphe** ou raccourci **Alt+Shift+G** sur le tableau de bord).",
+          "Choisir une **plage** : champs **Du** / **Au**, bouton **Aujourd’hui**, ou préréglages **jour** / **semaine** / **mois** / **année** (selon ce que l’UI expose).",
+          "Optionnel : **sélectionner** une ou plusieurs **#étiquettes** pour **restreindre** les tâches (les **sessions** **sans** tâche **correspondante** **disparaissent** des **vues** **basées** **tâches**).",
+          "Lire les **blocs** : **résumé**, **tableaux** par **jour**, **temps** par **@projet** / **#tag**, **navigation** de **semaine** **le** **cas** **échéant** ; **lancer** la **visite** **guidée** **si** la **pancarte** **le** **propose**."
+        ],
+        options: [
+          "**Indicateurs non finaux** (pastilles) : rappellent le **travail encore ouvert** dans la plage — lire prudemment, pas de chiffrage *figé* tant que des tâches *bougent* encore.",
+          "**Début de semaine** (lundi, dimanche ou samedi) : réglage souvent près des **calendriers** hebdo des rapports — choisissez **ce** qui coïncide avec **votre** semaine réelle.",
+          "Relancer la visite **Rapports** (aide **premier pas** sur l’écran) : [Paramètres — visite Rapports](/settings#settings-reporting-tour)."
+        ],
+      },
+      {
+        id: "ug-settings-integrations",
+        title: "Paramètres, sauvegardes et bouts d’usine (quand vous êtes prêt·e)",
+        searchIndex: "export backup sqlite json csv gitlab mongo v4 v4-dev next dev développement local",
+        paragraphs: [
+          "Ici, vous **réglez** l’**appareil** (KronoFocus, **étiquettes** / **@** avancés, planification) et, **seulement si** vous voulez, le **câble** (Git, GitLab, miroir). La **zone dangereuse** : **lisez** le texte à l’**écran** et la **phrase** de confirmation avant de **valider** un **effacement**. L’[index de la page Paramètres](/settings#settings-usage-profile) liste toutes les sections (sommaire à gauche en grand écran)."
+        ],
+        optionsTitle: "Principaux blocs (noms fréquents, selon votre version)",
+        options: [
+          "**Profil d’usage** ([ancre Profil d’utilisation](/settings#settings-usage-profile)) : ex. *gestion* masque des blocs (p. ex. Lignes de code) qu’un **dév** n’aurait pas caché.",
+          "[KronoFocus](/settings#settings-kronoFocus), [Collecte et tampons](/settings#settings-collection), [Horaire de travail](/settings#settings-schedule) ou [sessions planifiées](/settings#settings-planned-sessions), [Tâches et étiquettes](/settings#settings-task-tags) ; [Git](/settings#settings-git) / [MongoDB](/settings#settings-mongo) en branchement **opt-in** (rien n’impose d’ouvrir tout le premier soir).",
+          "**Corrections d’horaire** : commutateurs **on/off** dans [Tâches et étiquettes](/settings#settings-task-tags) pour le **début** et la **fin** d’une **tâche**, et le **début** et la **fin** d’une **session** (la fin : tâches et sessions déjà terminées).",
+          "**Général — mode développement (coffre local)** ([Paramètres → Général](/settings#settings-dev-data), seulement en `next dev`) : **Enregistrer** avec le bouton principal ; par défaut, **jeu de données** séparé de la **production** ; on peut partager le coffre `v4` (puis **redémarrer** le serveur de dev).",
+          "**Sauvegarde** (export) : côté technique l’**API** `GET /api/backup` sert le fichier (paramètre de **format**) ; côté **appli** voir aussi [Export par défaut](/settings#settings-export). L’**URL** de base et l’**install** = **README** côté déploiement."
+        ],
+        stepsTitle: "Avant d’effacer l’historique (check-list courte)",
+        steps: [
+          "Préférer un **export** (souvent proposé dans l’**écran** d’avertissement) : JSON, CSV, copie **SQLite** selon ce qu’ouvre la **brique** d’hébergement **chez** vous, ou l’[export par défaut](/settings#settings-export) dans l’**UI** quand c’est proposé.",
+          "Relire [la zone dangereuse](/settings#settings-danger-zone) (liste de ce **qui** **disparaît** *vraiment*).",
+          "Saisir le **mot** de confirmation *exact* demandé ; annuler s’il reste le **doute**."
+        ],
+      },
+    ],
+  };
+}
+
+function enBundle(): UserGuideBundle {
+  return {
+    pageTitle: "User guide",
+    pageSubtitle:
+      "Each section blends *why* it matters **to you**, **step-by-step** moves in the UI when order matters, and **options** you can actually pick — same **light or dark** look as the app.",
+    defaultStepBlockTitle: "Step by step in the app",
+    defaultOptionsBlockTitle: "Options, modes, and quick facts",
+    searchPlaceholder: "Filter topics (purpose, steps, options, KronoFocus…)",
+    searchAriaLabel: "Search the user guide",
+    searchNoResults: "No section matches. Try another keyword or clear the filter.",
+    tocHeading: "On this page",
+    tocNavAria: "User guide table of contents",
+    lastUpdated: "Last updated: April 2026",
+    sections: [
+      {
+        id: "ug-essence",
+        title: "What Kronosys is for — the heart, not the tab",
+        searchIndex:
+          "purpose why meaning help people benefit productivity time memory focus calm team client explain remember rhythm work life attention local your data",
+        paragraphs: [
+          "Kronosys is a **companion** for time and work: record **what** you are doing, **for how long**, in which **thread** — not to fill a paperwork show. **What is it for?** A little **less** amnesia about *“how much of my week was that, really?”*, a **clean** way to **end** a work block, and a **story** (for you, a team, a client) when the moment needs it.",
+          "Built for people who work in **chunks** (code, copy, operations, research…), **juggle** contexts, or have to **explain** without rebuilding Excel at midnight. Data stays **on your** machine; Git, mirrors, and large backups are **cables** you add when **you** choose.",
+        ],
+        optionsTitle: "Three “rooms” for three moves",
+        options: [
+          "**Dashboard** — the workbench (sessions, tasks, focus timer, **#** tags and **@** projects).",
+          "**Reports** — the look back (range, themes, charts: numbers come from what you **already** logged).",
+          "**Settings** — the back room (habits, connections, the **danger** zone where you wipe history **carefully**). [Open Settings](/settings#settings-usage-profile).",
+        ],
+        stepsTitle: "A calm first run (day one need not be perfect)",
+        steps: [
+          "Open the **home** (dashboard) — the workbench starts there.",
+          "Start a **new session** (or let the app start one the first time a task needs it).",
+          "Name a **task**; **#** = tag, **@** = project (the form often **suggests** both from what you type).",
+          "Press **Start** on the task, or add **KronoFocus** on the **side** if a ritual helps more than a bare timer in the list.",
+          "When you need the bigger picture, open **Reports** for a **date range** — you should not have to re-run the week in spreadsheets to see it.",
+        ],
+      },
+      {
+        id: "ug-nav-theme",
+        title: "Toolbar, theme, and language",
+        searchIndex: "theme light dark language fr en brand",
+        paragraphs: [
+          "The top bar reuses the **same** **family** of controls (zinc, **violet** accents) on every page so **navigation** stays **light** on the brain. The **cog** icon opens [Settings](/settings#settings-usage-profile) (shortcut **Alt+Shift+S** from the dashboard).",
+        ],
+        steps: [
+          "On the **dashboard**: **Book** → this guide; **chart** → **Reports**; **cog** → **Settings**.",
+          "On **other** pages: **grid** back to **home**; same book / chart / cog; on **Licenses** only, you also get a **file** icon.",
+          "**Theme** toggle: **light** or **dark** (evening work or a bright room).",
+          "**Refresh** fetches state again from the **server** (e.g. after a change you know happened elsewhere).",
+          "**Language** menu: **EN** / **FR**; if the server is configured, the choice can **stick** between visits.",
+        ],
+        options: [
+          "**Book** = this guide; **Chart** = **Reports**; **Cog** = **Settings**; **File** = **Licenses** (only on the licenses page).",
+          "The **theme** only changes how the **UI** looks — it does **not** alter your stored work.",
+        ],
+      },
+      {
+        id: "ug-layout",
+        title: "Where to work, where to look back, where to tune",
+        searchIndex: "workspace dashboard reports settings license legal",
+        paragraphs: [
+          "Three main moves: the workbench (now), **Reports** (then), **Settings** (how the app runs + serious cleanup). **Licenses** is the honest credit page for the open building blocks we use.",
+        ],
+        options: [
+          "**Dashboard** — **sessions** on the left, **tasks** in the **centre**, **tag** and **@** **shortcuts** on the right so you stop retyping the same words.",
+          "**Reports** — pick a **date range** and, if needed, **#** tags; read **summaries** and **charts**; the **tour** may offer itself the first time you land there.",
+          "**Settings** — profile, collection, scheduling, **advanced** tags, optional **Git** or **remote**; the **danger zone** can **delete** all **history** (type-to-confirm). [Settings overview](/settings#settings-usage-profile) · [danger zone](/settings#settings-danger-zone).",
+          "**Licenses** — MIT, third parties, **fonts**; the **file** icon **only** on that page.",
+        ],
+      },
+      {
+        id: "ug-sessions-tasks",
+        title: "Sessions, tasks, tags, and projects",
+        searchIndex: "session archive end task timer pause subtask",
+        paragraphs: [
+          "A **session** is the **bag** work piles into; a **task** is the **thread** of a moment. **#** and **@** are naming helpers, not a grammar test.",
+        ],
+        optionsTitle: "New session — the frame, your choice",
+        options: [
+          "**No** extra frame in particular: start, and the flow **carries** you.",
+          "**Max wall** clock: a **nudge** to reframe a **very** long stint.",
+          "**Calendar** window: from / to **dates** (a commitment to your later self or someone else).",
+          "**Week** + time window on selected **weekdays** (handy in a **fixed** rhythm; skip it if you hate that).",
+          "Tasks in **real time** or back-filled with start and end: honest to log the evening for **yesterday**’s work.",
+        ],
+        stepsTitle: "After you press “Start” on a task (usual order)",
+        steps: [
+          "Type a **title**; add **#** and/or **@** when the words come (a **live** **preview** often shows under the field).",
+          "Click **Start** on the task — or, if it fits, launch **KronoFocus** from that **task** first (same work, different rhythm).",
+          "If another **timer** is on: **pause** it, **finish** it, or allow both in **parallel** (you can **save** the choice for the next time).",
+          "While in progress: add **subtasks**; check them; **reorder** by **drag and drop**; use **pause** and **resume** kindly.",
+          "**End session** from the header or banner: optional end reason (on time, early, overrun, other + note) — a word for **how** the block **ended**, not a cold verdict.",
+        ],
+        bullets: [
+          "When **Commit** on **finish** appears, it is about **Git** (see [Git sync](/settings#settings-git) in **Settings**) — you can **ignore** it with a clear head if you are not in that workflow.",
+        ],
+      },
+      {
+        id: "ug-kronofocus",
+        title: "KronoFocus — the rhythm, not a report card",
+        searchIndex: "pomodoro timer focus work break duration",
+        paragraphs: [
+          "**Work**, **pause**, **resume**, long **pause**: the idea is **healthy** alternation at the **bench**, not a score in minutes. Close to a **Pomodoro** — without locking in if your day does not match.",
+        ],
+        optionsTitle: "Where to find it, what the controls do",
+        options: [
+          "In **Settings**: the [KronoFocus (dashboard)](/settings#settings-kronoFocus) section — show the timer in the **header** and/or **on** the **task** (your **usage** profile can hide other panels elsewhere in the app).",
+          "On the **card**: **Start**, **Pause**, resume; **duration** as `HH:MM:SS`; a **one-tap** default (e.g. 25 min); **history** of durations to **reapply** without retyping.",
+          "Link the timer to the **active** **task** so you can later see **which** **task** carried that focus block in the **archive**.",
+        ],
+        steps: [
+          "Open **KronoFocus** (header or on a **task**); pick **work** / **pause** / **long** **pause** from the state the bar shows.",
+          "Adjust the **duration**; add a favourite to **history** to reuse the same **measure** in one click.",
+          "Start the **count**down; when a phase ends, the **UI** suggests the **next** **step** in the current flow.",
+        ],
+      },
+      {
+        id: "ug-search-palette",
+        title: "Search: data (dashboard) and topics (this guide)",
+        searchIndex: "palette data search ctrl k",
+        paragraphs: [
+          "Same field **look** (zinc **border**, **violet** ring on **focus**): first the **workshop** (sessions, tasks, **#** / **@**); on **this** page, the line at the top only **filters** this help text.",
+        ],
+        stepsTitle: "Data — the search palette (dashboard)",
+        steps: [
+          "Click **search data** or press **Ctrl+K** (win/linux) / **⌘K** (mac) — the palette is **reserved**; you do **not** rebind that chord in the **shortcuts** **modal**.",
+          "Type a few **letters** of a **session**, **task**, **#**, or **@**; the list **tightens** as you type.",
+          "**Enter** a row to **jump**; **Esc** closes the box without a full **page** **reload**.",
+        ],
+        optionsTitle: "This guide — filter at the top of the page",
+        options: [
+          "It does **not** read your Kronosys database; it only **filters** the **sections** of this **guide** (titles and body) for **reading** here.",
+          "The **n / total** to the right of the field: how many **headings** stay **visible** after you type.",
+        ],
+      },
+      {
+        id: "ug-shortcuts",
+        title: "Keyboard shortcuts (dashboard)",
+        searchIndex: "keyboard hotkey alt shift",
+        paragraphs: [
+          "Open the **shortcuts** modal (small keyboard by the **search** **trigger**) to view, rebind, or **reset** combinations. **Ctrl+K** / **⌘K** stay reserved for the **data** **palette**. Re-running some **tours** and the **API** options live under [Settings — dashboard & API](/settings#settings-web).",
+        ],
+        bullets: [
+          "New session: Alt+Shift+N (default).",
+          "Reporting: Alt+Shift+G · Settings: Alt+Shift+S · **This guide**: Alt+Shift+U.",
+          "Columns: Ctrl+Alt+H (sessions) · J (tasks) · Y (tags & projects).",
+          "Theme: Alt+Shift+T · Language: Alt+Shift+L · End live session: Alt+Shift+E.",
+        ],
+      },
+      {
+        id: "ug-reporting",
+        title: "Reports: memory you can read back, not a verdict on you",
+        searchIndex: "filter date tag week kpi punctuality late schedule planned",
+        paragraphs: [
+          "Reports are for a **calm** read of a time span, not a moral tally. They help answer: can we, together, make sense of this **period**? Unfinished work stays **indicated** where the UI does — honest draft, not **punishment**.",
+          "The app **aggregates** what you **already** recorded (durations, tags, projects), sometimes with code-related lines and a **folder** peek if that is **on** in your **setup**; a **guided** **tour** may soften the **first** visit.",
+          "If the **recording** **host** **passed** a **planned** start instant when a session was opened (for example a worker tied to your [work schedule](/settings#settings-schedule) or [planned sessions](/settings#settings-planned-sessions)), the app stores the **offset** in minutes and shows **punctuality** **summary** KPIs on **Reporting** — a browser-only **New session** usually does **not** set this by itself, unless a connector does.",
+        ],
+        stepsTitle: "A typical run on the Reports page",
+        steps: [
+          "Open **Reports** (chart icon, or **Alt+Shift+G** from the dashboard).",
+          "Set **from** and **to** (or a day / week / month / year **preset**, depending on what the UI offers).",
+          "Use **Today** / **Now** quick actions in date/time pickers whenever available to jump to the current value.",
+          "Optionally pick one or more **#** **tags** (sessions with **no** **matching** task may **disappear** from some **task**-based **views**).",
+          "Scroll the **summary**, per-day **tables**, **@project** / **#tag** **breakdowns**, and the week nudger when your data has **enough** **weeks** to flip through.",
+          "Start the **guided** **tour** if a prompt appears the **first** time.",
+        ],
+        options: [
+          "**Non-final** chips mark work that is not **closed** in the **range** you are looking at: read them gently; the **draft** is not a **failure**.",
+          "**Week** starts on (Monday, Sunday, or Saturday) — often next to the tag-week **grids**; pick the one that **matches** how you read a week.",
+          "Re-launch the **Reports** first-time **tour** from [Settings — Reporting tour](/settings#settings-reporting-tour).",
+        ],
+      },
+      {
+        id: "ug-settings-integrations",
+        title: "Settings, safety copies, and extra wiring (when you are ready)",
+        searchIndex: "export backup sqlite json gitlab mongo v4 v4-dev next dev local development",
+        paragraphs: [
+          "Here you tune how the app **presents** itself (KronoFocus, tags and **@** **advanced** paths, **schedule**) and, only if you want, the **cable** to **Git**, GitLab, a **mirror**… The **danger** **zone** — read the on-screen text and the **type**-**to**-**confirm** line before a full **wipe**. The [Settings page index](/settings#settings-usage-profile) links every section (left-hand **TOC** on a wide window).",
+        ],
+        optionsTitle: "What you are likely to find (names can vary with version)",
+        options: [
+          "**Usage** profile ([Usage profile section](/settings#settings-usage-profile)): e.g. *manager* hides some developer-heavy **panels** you might still want in *dev* mode.",
+          "[KronoFocus](/settings#settings-kronoFocus), [Collection & buffers](/settings#settings-collection), [work schedule](/settings#settings-schedule) or [planned sessions](/settings#settings-planned-sessions), [Tasks & tags](/settings#settings-task-tags) ; [Git](/settings#settings-git) / [MongoDB mirror](/settings#settings-mongo) as **opt-in** (nothing forces you to turn everything on day one).",
+          "**Time correction**: **on/off** toggles in [Tasks & tags](/settings#settings-task-tags) for **task** and **session** **start** times, plus separate toggles for **end** times on **completed** tasks and **finished** sessions.",
+          "**General — local development (data store)** ([Settings → General](/settings#settings-dev-data), only under `next dev`): use the main **Save** button; by default, **dev** uses a **separate** data folder from **production**; you can opt into the same `v4` path, then **restart** the dev server.",
+          "**Backup** (export): technically `GET /api/backup` with a **format** query; in the app see also [Export defaults](/settings#settings-export). Base URL and deployment = **README** in your **environment**, not this page alone.",
+        ],
+        stepsTitle: "Before clearing all history (short list)",
+        steps: [
+          "Prefer an **export** when the UI or hosting layer offers it (JSON, CSV, or **SQLite** copy, depending on what your stack exposes), or [Export defaults](/settings#settings-export) when the UI offers it.",
+          "Re-read the [danger zone](/settings#settings-danger-zone): what **actually** **goes** **away**.",
+          "Type the **confirmation** word **exact**ly; use **Cancel** if doubt remains.",
+        ],
+      },
+    ],
+  };
+}
+
+function stripInternalGuideLinks(s: string): string {
+  return s.replace(/\[([^\]]+)\]\(\/[^)]+\)/g, "$1");
+}
+
+function stripSimpleMarkdown(s: string): string {
+  return s.replaceAll("**", "");
+}
+
+/** Même champs qu’en affichage, moins le gras et la syntaxe des liens (pour l’index de recherche). */
+function stripForSearch(s: string): string {
+  return stripSimpleMarkdown(stripInternalGuideLinks(s));
+}
+
+export function userGuideBundle(lang: Lang): UserGuideBundle {
+  return lang === "fr" ? frBundle() : enBundle();
+}
+
+/** Texte d’index pour la recherche (titre, paragraphes, puce, index explicite). */
+export function sectionSearchHaystack(s: UserGuideSection): string {
+  const p = s.paragraphs.map(stripForSearch).join(" ");
+  const b = (s.bullets ?? []).map(stripForSearch).join(" ");
+  const st = (s.steps ?? []).map(stripForSearch).join(" ");
+  const o = (s.options ?? []).map(stripForSearch).join(" ");
+  return `${s.title} ${p} ${b} ${st} ${o} ${s.searchIndex}`.toLowerCase();
+}

package/lib/workspaceLocDefaults.ts

@@ -0,0 +1,21 @@
+/**
+ * Valeurs par défaut pour le formulaire Paramètres (instantané lignes de code).
+ * À tenir aligné avec `src/workspaceLocConfig.ts` et package.json.
+ */
+export const DEFAULT_WORKSPACE_LOC_EXCLUDED_DIRECTORY_NAMES: readonly string[] = [
+  "node_modules",
+  ".git",
+  "dist",
+  "out",
+  "build",
+  ".next",
+  "coverage",
+  "target",
+  "__pycache__",
+  ".venv",
+  "venv",
+  "vendor",
+  ".turbo",
+  ".cache",
+  ".idea",
+] as const;

package/next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+import "./.next/types/routes.d.ts";
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/next.config.ts

@@ -0,0 +1,15 @@
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { NextConfig } from "next";
+
+const appDir = path.dirname(fileURLToPath(import.meta.url));
+
+const nextConfig: NextConfig = {
+  turbopack: {
+    root: appDir,
+  },
+  serverExternalPackages: ["better-sqlite3"],
+  outputFileTracingRoot: appDir,
+};
+
+export default nextConfig;

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@nightkatana/kronosys-app",
+  "version": "1.0.0-beta.0",
+  "description": "Kronosys — application Next.js (UI + API + SQLite).",
+  "license": "MIT",
+  "author": "nightkatana",
+  "packageManager": "npm@11.3.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "kronosys": "./bin/kronosys.mjs"
+  },
+  "files": [
+    "README.md",
+    "bin",
+    "app",
+    "components",
+    "lib",
+    "public",
+    "server",
+    "next.config.ts",
+    "postcss.config.mjs",
+    "tsconfig.json",
+    "next-env.d.ts"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "volta": {
+    "node": "22.22.0",
+    "npm": "11.3.0"
+  },
+  "scripts": {
+    "dev": "next dev --webpack -H kronosys -p 5555",
+    "dev:e2e": "next dev --webpack -H 127.0.0.1 -p 5555",
+    "build": "next build --webpack",
+    "start": "next start -p 5555",
+    "lint": "eslint",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage --reporter=default --reporter=junit --outputFile.junit=reports/vitest-junit.xml",
+    "test:watch": "vitest",
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui",
+    "test:e2e:install": "playwright install chromium",
+    "prepare": "husky",
+    "prepublishOnly": "npm run build",
+    "hooks:install": "husky",
+    "pack:release": "bash scripts/pack-with-zip.sh",
+    "changeset": "changeset",
+    "changelog:build": "node scripts/build-user-changelog.mjs",
+    "version:release": "changeset version && npm run changelog:build"
+  },
+  "dependencies": {
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
+    "better-sqlite3": "^12.9.0",
+    "date-fns": "^4.1.0",
+    "fflate": "^0.8.2",
+    "lucide-react": "^1.8.0",
+    "mongodb": "^6.21.0",
+    "next": "16.2.3",
+    "react": "19.2.4",
+    "react-day-picker": "^9.14.0",
+    "react-dom": "19.2.4"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.31.0",
+    "@playwright/test": "^1.59.1",
+    "@tailwindcss/postcss": "^4",
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^22.15.21",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "@vitest/coverage-v8": "^3.2.4",
+    "eslint": "^9",
+    "eslint-config-next": "16.2.3",
+    "husky": "^9.1.7",
+    "jsdom": "^26.1.0",
+    "tailwindcss": "^4",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  }
+}

package/postcss.config.mjs

@@ -0,0 +1,12 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const appRoot = path.dirname(fileURLToPath(import.meta.url));
+
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": { base: appRoot },
+  },
+};
+
+export default config;

package/public/file.svg

@@ -0,0 +1 @@
+<svg fill="none" viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg"><path d="M14.5 13.5V5.41a1 1 0 0 0-.3-.7L9.8.29A1 1 0 0 0 9.08 0H1.5v13.5A2.5 2.5 0 0 0 4 16h8a2.5 2.5 0 0 0 2.5-2.5m-1.5 0v-7H8v-5H3v12a1 1 0 0 0 1 1h8a1 1 0 0 0 1-1M9.5 5V2.12L12.38 5zM5.13 5h-.62v1.25h2.12V5zm-.62 3h7.12v1.25H4.5zm.62 3h-.62v1.25h7.12V11z" clip-rule="evenodd" fill="#666" fill-rule="evenodd"/></svg>

package/public/globe.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><g clip-path="url(#a)"><path fill-rule="evenodd" clip-rule="evenodd" d="M10.27 14.1a6.5 6.5 0 0 0 3.67-3.45q-1.24.21-2.7.34-.31 1.83-.97 3.1M8 16A8 8 0 1 0 8 0a8 8 0 0 0 0 16m.48-1.52a7 7 0 0 1-.96 0H7.5a4 4 0 0 1-.84-1.32q-.38-.89-.63-2.08a40 40 0 0 0 3.92 0q-.25 1.2-.63 2.08a4 4 0 0 1-.84 1.31zm2.94-4.76q1.66-.15 2.95-.43a7 7 0 0 0 0-2.58q-1.3-.27-2.95-.43a18 18 0 0 1 0 3.44m-1.27-3.54a17 17 0 0 1 0 3.64 39 39 0 0 1-4.3 0 17 17 0 0 1 0-3.64 39 39 0 0 1 4.3 0m1.1-1.17q1.45.13 2.69.34a6.5 6.5 0 0 0-3.67-3.44q.65 1.26.98 3.1M8.48 1.5l.01.02q.41.37.84 1.31.38.89.63 2.08a40 40 0 0 0-3.92 0q.25-1.2.63-2.08a4 4 0 0 1 .85-1.32 7 7 0 0 1 .96 0m-2.75.4a6.5 6.5 0 0 0-3.67 3.44 29 29 0 0 1 2.7-.34q.31-1.83.97-3.1M4.58 6.28q-1.66.16-2.95.43a7 7 0 0 0 0 2.58q1.3.27 2.95.43a18 18 0 0 1 0-3.44m.17 4.71q-1.45-.12-2.69-.34a6.5 6.5 0 0 0 3.67 3.44q-.65-1.27-.98-3.1" fill="#666"/></g><defs><clipPath id="a"><path fill="#fff" d="M0 0h16v16H0z"/></clipPath></defs></svg>