retold-content-system 1.0.0

package/docs/cover.md

@@ -0,0 +1,16 @@
+# Retold Content System
+
+> Edit and preview markdown content folders from any browser.
+
+A local-first content editor and documentation viewer built on the Retold ecosystem. Point it at any folder of markdown files and get a full editing environment with syntax highlighting, live preview, image uploads, file browsing, and documentation topics management.
+
+- **Edit** -- Rich markdown editor with CodeMirror, section segmentation, and inline controls
+- **Browse** -- File tree sidebar with navigation, new file creation, and image uploads
+- **Preview** -- Live rendered markdown reference panel with synchronized scrolling
+- **Code** -- Syntax-highlighted editor for JSON, HTML, YAML, and 190+ languages via highlight.js
+- **Topics** -- Manage documentation topic manifests linking help codes to files and line numbers
+
+[Getting Started](getting-started.md)
+[Editor Guide](editor-guide.md)
+[Command Line](cli.md)
+[GitHub](https://github.com/stevenvelozo/retold)

package/docs/css/docuserve.css

@@ -0,0 +1,73 @@
+/* ============================================================================
+   Pict Docuserve - Base Styles
+   ============================================================================ */
+
+/* Reset and base */
+*, *::before, *::after {
+	box-sizing: border-box;
+}
+
+html, body {
+	margin: 0;
+	padding: 0;
+	font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+	font-size: 16px;
+	line-height: 1.5;
+	color: #423D37;
+	background-color: #fff;
+	-webkit-font-smoothing: antialiased;
+	-moz-osx-font-smoothing: grayscale;
+}
+
+/* Typography */
+h1, h2, h3, h4, h5, h6 {
+	margin-top: 0;
+	line-height: 1.3;
+}
+
+a {
+	color: #2E7D74;
+	text-decoration: none;
+}
+
+a:hover {
+	color: #256861;
+}
+
+/* Application container */
+#Docuserve-Application-Container {
+	min-height: 100vh;
+}
+
+/* Utility: scrollbar styling */
+::-webkit-scrollbar {
+	width: 8px;
+}
+
+::-webkit-scrollbar-track {
+	background: #F5F0E8;
+}
+
+::-webkit-scrollbar-thumb {
+	background: #D4CCBE;
+	border-radius: 4px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+	background: #B5AA9A;
+}
+
+/* Responsive adjustments */
+@media (max-width: 768px) {
+	html {
+		font-size: 14px;
+	}
+
+	#Docuserve-Sidebar-Container {
+		display: none;
+	}
+
+	.docuserve-body {
+		flex-direction: column;
+	}
+}

package/docs/editor-guide.md

@@ -0,0 +1,137 @@
+# Editor Guide
+
+The content editor is a browser-based application for editing markdown files and other text content. Open it by navigating to `/edit.html` on your running content system server.
+
+## Layout
+
+The editor has three main areas:
+
+- **Top Bar** -- Shows the application name, current file name, save status, word/character stats, and action buttons (Save, Close).
+- **Sidebar** -- A collapsible panel on the left with three tabs: Files, Reference, and Topics.
+- **Editor Pane** -- The main editing area, which switches between a markdown editor and a code editor depending on the file type.
+
+## File Browser
+
+The **Files** tab in the sidebar shows the directory tree of your content folder. Click any file to open it in the editor. The browser supports:
+
+- Navigating into subfolders by clicking folder names
+- Breadcrumb navigation to move back up the directory tree
+- A **New File** button (`+`) to create new markdown files
+- An **Upload Image** button to add images to the current directory
+
+### Creating a New File
+
+Click the `+` button in the sidebar header. A form appears where you enter the filename. The file is created in the directory you are currently browsing. If you include a path separator (e.g. `guides/setup.md`), intermediate directories are created automatically.
+
+### Uploading Images
+
+Click the upload button (or press `Cmd+Shift+U` / `Ctrl+Shift+U`) to open the upload overlay. Drag an image onto the drop zone or click to select a file. The image is uploaded to the folder you are currently browsing, and a markdown image reference is copied to your clipboard for easy pasting into your document.
+
+### Hidden Files
+
+By default the file browser hides dotfiles and other hidden files. To show them, open the **Settings** gear icon in the sidebar and check **Show Hidden Files**.
+
+## Markdown Editor
+
+When you open a `.md` file, the editor loads a full CodeMirror-based markdown editing environment. Features include:
+
+- Syntax highlighting for markdown
+- Line numbers
+- Word wrap (toggleable in settings)
+- Editing controls toolbar with bold, italic, heading, link, image, list, code, and blockquote buttons
+- Auto-segmentation that splits long documents into editable sections at heading boundaries
+
+### Editing Controls
+
+The toolbar above the editor provides one-click formatting. Select text and click a button to wrap it, or click with no selection to insert a template. Available controls:
+
+| Button | Action |
+|--------|--------|
+| **B** | Bold (`**text**`) |
+| *I* | Italic (`*text*`) |
+| H1-H3 | Insert heading |
+| Link | Insert `[text](url)` |
+| Image | Insert `![alt](url)` |
+| List | Insert bulleted list item |
+| Code | Insert inline code or fenced code block |
+| Quote | Insert blockquote |
+
+### Auto-Segmentation
+
+For long markdown files, enable **Auto-Segment Markdown** in the settings panel. This splits the document at heading boundaries into independently scrollable editor segments. You can set the segmentation depth (H1 only, H1-H2, etc.) to control how finely the document is divided. Each segment gets its own CodeMirror editor instance.
+
+## Code Editor
+
+Non-markdown text files (JSON, HTML, CSS, JavaScript, YAML, and 190+ other languages) open in a CodeJar-based code editor with highlight.js syntax highlighting. The editor automatically detects the language from the file extension.
+
+The code editor supports:
+
+- Syntax highlighting for the detected language
+- Tab indentation
+- Line numbers
+- Auto-closing brackets and quotes
+- Word wrap (toggleable independently from the markdown editor)
+
+## Saving Files
+
+Press `Cmd+S` (Mac) or `Ctrl+S` (Windows/Linux) to save the current file. The top bar shows save status:
+
+- A gold **\*** next to the filename indicates unsaved changes
+- **Saving...** appears during the save request
+- **Saved** appears briefly on success
+- **Save failed** appears if something goes wrong
+
+The **Save** button only appears when you have unsaved changes.
+
+## Closing Files
+
+Press `Escape` or click the **Close** button in the top bar to close the current file. If you have unsaved changes, a confirmation dialog appears asking whether to discard changes or cancel.
+
+The confirmation dialog supports keyboard shortcuts:
+
+- `Y` -- Discard changes and close
+- `N` or `Escape` -- Cancel and return to editing
+
+## Sidebar Tabs
+
+### Files Tab
+
+The default tab showing the file browser tree. See the File Browser section above.
+
+### Reference Tab
+
+Press `F1` to toggle the Reference tab, which shows a live rendered preview of the current markdown file. The reference panel updates every time you save. This is useful for checking how your markdown renders while editing.
+
+The reference panel includes a **View in Reader** link that opens the current file in the documentation reader (`/` route) in a new tab.
+
+### Topics Tab
+
+Press `F4` or `Cmd+Shift+T` / `Ctrl+Shift+T` to open the Topics tab. This panel manages `.pict_documentation_topics.json` files -- JSON manifests that map topic codes to help file paths and titles. See [Documentation Topics](topics.md) for details.
+
+## Settings
+
+Click the gear icon in the sidebar header to open the settings flyout. Available settings:
+
+### Markdown Settings
+
+- **Auto-Segment Markdown** -- Split documents at heading boundaries
+- **Segmentation Depth** -- How deep to segment (H1, H2, H3)
+- **Show Editing Controls** -- Toggle the formatting toolbar
+- **Word Wrap** -- Enable word wrap in the markdown editor
+- **Auto Content Preview** -- Automatically show the Reference panel
+
+### Code Editor Settings
+
+- **Word Wrap (Code)** -- Enable word wrap in the code editor
+
+### Media Preview Settings
+
+- **Auto-Preview Images** -- Show image thumbnails in the file browser
+- **Auto-Preview Video** -- Show video players for video files
+- **Auto-Preview Audio** -- Show audio players for audio files
+
+### File Browser Settings
+
+- **Show Hidden Files** -- Include dotfiles and hidden files in the file browser
+
+Settings are persisted in your browser's localStorage and restored on each visit.

package/docs/getting-started.md

@@ -0,0 +1,73 @@
+# Getting Started
+
+The Retold Content System is a local markdown editor and documentation viewer. Install it once with npm and point it at any folder of markdown files.
+
+## Installation
+
+Install globally from npm:
+
+```bash
+npm install -g retold-content-system
+```
+
+This gives you two equivalent CLI commands: `retold-content-system` and `rcs`.
+
+## Quick Start
+
+Create a folder with some markdown files and serve it:
+
+```bash
+mkdir my-docs
+cd my-docs
+echo "# Hello World" > README.md
+rcs serve
+```
+
+The server starts on a random port between 7000 and 7999 and prints the URLs for both the reader and the editor:
+
+```
+  Retold Content System running on http://localhost:7042
+  Reader:  http://localhost:7042/
+  Editor:  http://localhost:7042/edit.html
+```
+
+Open the **Reader** URL for a pict-docuserve documentation viewer, or the **Editor** URL for the full editing environment.
+
+## Choosing a Port
+
+Pass `-p` to pin the server to a specific port:
+
+```bash
+rcs serve -p 8080
+```
+
+## Pointing at a Different Folder
+
+Provide a content path as the first argument:
+
+```bash
+rcs serve ~/projects/my-wiki
+```
+
+If the target directory has a `content/` subfolder, the server uses that automatically. This means running `rcs serve` from a project root that has a `content/` directory does the right thing without extra arguments.
+
+## What Gets Served
+
+The content system sets up three static routes and several API endpoints:
+
+| Route | Purpose |
+|-------|---------|
+| `/` | Documentation reader (pict-docuserve) |
+| `/edit.html` | Content editor application |
+| `/content/*` | Raw content files (markdown, images, etc.) |
+| `/uploads/*` | Uploaded images |
+| `/api/filebrowser/*` | File listing API |
+| `/api/content/read/*` | File content read API |
+| `/api/content/save/*` | File content save API |
+| `/api/content/upload-image` | Image upload endpoint |
+
+## Next Steps
+
+- Read the [Editor Guide](editor-guide.md) for a walkthrough of the editing UI
+- See the [CLI Reference](cli.md) for all command-line options
+- Learn about [Documentation Topics](topics.md) for managing help topic manifests

package/docs/index.html

@@ -0,0 +1,39 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8">
+		<meta http-equiv="X-UA-Compatible" content="IE=edge">
+		<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+		<meta name="description" content="Documentation powered by pict-docuserve">
+
+		<title>Documentation</title>
+
+		<!-- Application Stylesheet -->
+		<link href="css/docuserve.css" rel="stylesheet">
+		<!-- KaTeX stylesheet for LaTeX equation rendering -->
+		<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css">
+		<!-- PICT Dynamic View CSS Container -->
+		<style id="PICT-CSS"></style>
+
+		<!-- Load the PICT library from jsDelivr CDN -->
+		<script src="https://cdn.jsdelivr.net/npm/pict@1/dist/pict.min.js" type="text/javascript"></script>
+		<!-- Bootstrap the Application -->
+		<script type="text/javascript">
+//<![CDATA[
+		Pict.safeOnDocumentReady(() => { Pict.safeLoadPictApplication(PictDocuserve, 2)});
+//]]>
+		</script>
+	</head>
+	<body>
+		<!-- The root container for the Pict application -->
+		<div id="Docuserve-Application-Container"></div>
+
+		<!-- Mermaid diagram rendering -->
+		<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
+		<script>mermaid.initialize({ startOnLoad: false, theme: 'default' });</script>
+		<!-- KaTeX for LaTeX equation rendering -->
+		<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.js"></script>
+		<!-- Load the Docuserve PICT Application Bundle from jsDelivr CDN -->
+		<script src="https://cdn.jsdelivr.net/npm/pict-docuserve@0/dist/pict-docuserve.min.js" type="text/javascript"></script>
+	</body>
+</html>

package/docs/keyboard-shortcuts.md

@@ -0,0 +1,40 @@
+# Keyboard Shortcuts
+
+All keyboard shortcuts work while the editor is focused. On Mac, `Cmd` is the modifier; on Windows and Linux, use `Ctrl`.
+
+## File Operations
+
+| Shortcut | Action |
+|----------|--------|
+| `Cmd+S` / `Ctrl+S` | Save the current file |
+| `Escape` | Close the current file (prompts if unsaved) |
+
+## Close Confirmation Dialog
+
+When closing a file with unsaved changes, the confirmation dialog responds to:
+
+| Key | Action |
+|-----|--------|
+| `Y` | Discard changes and close |
+| `N` | Cancel (keep editing) |
+| `Escape` | Cancel (keep editing) |
+
+## Sidebar Navigation
+
+| Shortcut | Action |
+|----------|--------|
+| `F1` | Toggle the Reference (preview) panel |
+| `F2` | Toggle the sidebar open/closed |
+| `F3` or `Cmd+Shift+U` / `Ctrl+Shift+U` | Open the image upload form |
+| `F4` or `Cmd+Shift+T` / `Ctrl+Shift+T` | Open Topics tab (creates a linked topic if in a markdown file) |
+
+## F4 Context-Aware Behavior
+
+When pressed while editing a markdown file, `F4` does more than just switch tabs. It:
+
+1. Reads the current cursor line number in the markdown editor
+2. Extracts the first heading from the document as a default title
+3. Creates a new topic entry linked to the current file and line number
+4. Opens the Topics tab with the new entry in edit mode
+
+When pressed while editing a non-markdown file or with no file open, `F4` simply switches the sidebar to the Topics tab.

package/docs/retold-catalog.json

@@ -0,0 +1,81 @@
+{
+	"Generated": "2026-02-22T20:41:55.752Z",
+	"GitHubOrg": "stevenvelozo",
+	"DefaultBranch": "master",
+	"Groups": [
+		{
+			"Name": "Dist",
+			"Key": "dist",
+			"Description": "",
+			"Modules": [
+				{
+					"Name": "css",
+					"Repo": "css",
+					"Group": "dist",
+					"Branch": "master",
+					"HasDocs": false,
+					"HasCover": false,
+					"Sidebar": [],
+					"DocFiles": []
+				},
+				{
+					"Name": "indoctrinate_content_staging",
+					"Repo": "indoctrinate_content_staging",
+					"Group": "dist",
+					"Branch": "master",
+					"HasDocs": false,
+					"HasCover": false,
+					"Sidebar": [],
+					"DocFiles": []
+				},
+				{
+					"Name": "js",
+					"Repo": "js",
+					"Group": "dist",
+					"Branch": "master",
+					"HasDocs": false,
+					"HasCover": false,
+					"Sidebar": [],
+					"DocFiles": []
+				}
+			]
+		},
+		{
+			"Name": "Source",
+			"Key": "source",
+			"Description": "",
+			"Modules": [
+				{
+					"Name": "cli",
+					"Repo": "cli",
+					"Group": "source",
+					"Branch": "master",
+					"HasDocs": false,
+					"HasCover": false,
+					"Sidebar": [],
+					"DocFiles": []
+				},
+				{
+					"Name": "providers",
+					"Repo": "providers",
+					"Group": "source",
+					"Branch": "master",
+					"HasDocs": false,
+					"HasCover": false,
+					"Sidebar": [],
+					"DocFiles": []
+				},
+				{
+					"Name": "views",
+					"Repo": "views",
+					"Group": "source",
+					"Branch": "master",
+					"HasDocs": false,
+					"HasCover": false,
+					"Sidebar": [],
+					"DocFiles": []
+				}
+			]
+		}
+	]
+}

package/docs/retold-keyword-index.json

@@ -0,0 +1,19 @@
+{
+	"Generated": "2026-02-22T20:41:55.835Z",
+	"DocumentCount": 0,
+	"LunrIndex": {
+		"version": "2.3.9",
+		"fields": [
+			"title",
+			"module",
+			"group",
+			"body"
+		],
+		"fieldVectors": [],
+		"invertedIndex": [],
+		"pipeline": [
+			"stemmer"
+		]
+	},
+	"Documents": {}
+}

package/docs/topics.md

@@ -0,0 +1,83 @@
+# Documentation Topics
+
+The Topics system manages `.pict_documentation_topics.json` files -- JSON manifests that map topic codes to documentation files. These manifests are used by applications with built-in help systems to link context-sensitive help codes to specific markdown files and line numbers.
+
+## Topics File Format
+
+A topics file is a JSON object where each key is a unique topic code:
+
+```json
+{
+    "Getting-Started": {
+        "TopicCode": "Getting-Started",
+        "TopicHelpFilePath": "guides/getting-started.md",
+        "TopicTitle": "Getting Started Guide"
+    },
+    "Max-Function": {
+        "TopicCode": "Max-Function",
+        "TopicHelpFilePath": "functions/func-reference-max.md",
+        "TopicTitle": "Max function",
+        "RelevantMarkdownLine": 23
+    }
+}
+```
+
+### Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `TopicCode` | Yes | A unique string identifier for the topic. Used as the lookup key by applications. |
+| `TopicHelpFilePath` | Yes | Relative path from the content root to the markdown file for this topic. |
+| `TopicTitle` | Yes | Human-readable title for the topic. |
+| `RelevantMarkdownLine` | No | Line number in the markdown file where the relevant content begins. Used for scrolling to context. |
+
+## Using the Topics Panel
+
+Open the Topics tab by pressing `F4` or `Cmd+Shift+T` / `Ctrl+Shift+T`, or by clicking the **Topics** tab in the sidebar.
+
+### Loading a Topics File
+
+On first launch, the editor attempts to load `.pict_documentation_topics.json` from the content root. If the file does not exist, the panel shows an empty state with two options:
+
+- **Load .pict_documentation_topics.json** -- Creates the default file and opens it
+- **Select file...** -- Enter a custom path to a topics JSON file anywhere in your content folder
+
+The topics file path is persisted in your browser settings and restored on future visits.
+
+### Adding Topics
+
+Click the **+ Add Topic** button at the bottom of the topic list. A new row appears in edit mode with empty fields. Fill in the topic code, title, and file path, then click **Save**.
+
+### Quick Topic from Cursor (F4)
+
+While editing a markdown file, press `F4` to create a topic pre-filled with:
+
+- **TopicHelpFilePath** set to the current file
+- **RelevantMarkdownLine** set to your cursor's line number
+- **TopicTitle** set to the first heading found in the document
+
+The Topics tab opens with the new entry in edit mode so you can adjust the topic code and title before saving.
+
+### Editing Topics
+
+Click the pencil icon on any topic row to switch it to inline edit mode. The row expands to show fields for all four properties. Click **Save** to commit changes or **Cancel** to discard.
+
+If you change a topic code, the editor checks for uniqueness. Duplicate codes are not allowed.
+
+### Deleting Topics
+
+Click the trash icon on a topic row. A browser confirmation dialog appears. Once confirmed, the topic is removed and the file is saved.
+
+### Navigating to a Topic's File
+
+Click the arrow icon on a topic row to open that topic's linked file in the editor. If the topic has a `RelevantMarkdownLine`, the editor scrolls to that line after opening the file.
+
+### Closing the Topics File
+
+Click the **X** button in the topics panel header to unload the topics file and return to the empty state. The topics file itself is not deleted -- it remains on disk.
+
+## Integration with Applications
+
+Applications that use `.pict_documentation_topics.json` can load the manifest and look up topics by code to show context-sensitive help. For example, a form builder might use `TopicCode` values to link each field to a help article, then open the documentation reader at the relevant file and line.
+
+The content system's reader app (served at `/`) can display any markdown file from the content folder, making it a natural companion for the topics manifest.