Improve/docs

README.md

@@ -15,17 +15,21 @@
 
 
 
-Satiscode is a lightweight Windows editor for C/C++, Python, JSON, and XML, built with Electron and Monaco Editor.
+Satiscode is a lightweight Windows editor for C/C++, Python, JSON, XML, web languages, and Markdown, built with Electron and Monaco Editor.
+
+For installation and a walkthrough of the editor, see the [Satiscode usage guide](USAGE.md).
 
 ## Features
 
 - C and C++ language detection by file extension
-- Python language detection by file extention
+- Python language detection by file extension
 - Web language detection for HTML, CSS/SCSS, JavaScript/JSX, TypeScript/TSX, and JSON
 - clangd diagnostics, completion, hover, and go-to-definition
-- PyRight diagnostics, completion, hover and go-to-definition for python
+- Pyright diagnostics, completion, hover, and go-to-definition for Python
 - FIXSON diagnostics, completion, and hover for JSON
-- FIXML well-formedness diagnostics, element completion, and hover for XML
+- FIXML diagnostics, element completion, and hover for XML
+- Markdown preview and edit modes
+- Git status, staging, commits, pull, push, and blame
 - VS Code-style Problems panel with clickable diagnostics
 - Resizable Explorer file tree for the current directory
 - New, Open, Save, Save As, and graceful Exit operations
@@ -41,7 +45,7 @@ Satiscode is a lightweight Windows editor for C/C++, Python, JSON, and XML, buil
 - Windows 10 or newer
 - Node.js 20 or newer
 
-The editor remains usable when python is unavailable, but PyRight language server will not function correctly.
+The editor remains usable when Python is unavailable, but Python language services will not function correctly.
 
 >[!NOTE]
 > Please NOTE That from satiscode 1.2.0 onwards LLVM does not need to be installed. All new builds will contain clangd and its librarys and later there will be instructions for local testing.
@@ -60,16 +64,17 @@ npm start
 >[!WARNING]
 > A clean source checkout runs without clangd or Pyright because their server files are absent; the editor can still open and edit supported file types. Source mode looks for clangd in `bin/` and Pyright in `PythonLSP/` at the repository root. `npm run build` installs and compiles FIXSON and FIXML from their package directories; packaged builds include both bundles in the application resources.
 
-Opening a `.c`, `.cc`, `.cpp`, `.cxx`, `.h`, `.hh`, `.hpp`, or `.hxx` file starts clangd only when its server files are available. Opening a `.py` file starts Pyright only when its server files are available. Opening a `.json` file starts FIXSON; `.jsonc` files retain Monaco's built-in support without strict JSON validation. XML documents (`.xml`, `.xsd`, `.xsl`, `.xslt`, `.svg`, and `.plist`) start FIXML. HTML, CSS, JavaScript, and TypeScript use Monaco's built-in language support.
+Opening a `.c`, `.cc`, `.cpp`, `.cxx`, `.h`, `.hh`, `.hpp`, or `.hxx` file starts clangd only when its server files are available. Opening a `.py` file starts Pyright only when its server files are available. Opening a `.json` file starts FIXSON; `.jsonc` files retain Monaco's built-in support without strict JSON validation. XML documents (`.xml`, `.xsd`, `.xsl`, `.xslt`, `.svg`, and `.plist`) start FIXML. HTML, CSS/SCSS, JavaScript/JSX, and TypeScript/TSX use Monaco's built-in language support. Markdown files (`.md` and `.markdown`) open in preview mode and can be switched to source editing.
 
 ## Keyboard shortcuts
 
 - `Ctrl+N`: New file
 - `Ctrl+O`: Open file
+- `Ctrl+K`: Open folder
 - `Ctrl+S`: Save
 - `Ctrl+Shift+S`: Save As
-- `Ctrl+f`: Find
-- `Ctrl+.`: Toggle Problems pannel
+- `Ctrl+F`: Find
+- `Ctrl+.`: Toggle Problems panel
 
 ## Build the Windows installer
 
@@ -113,3 +118,10 @@ Thanks to these awesome people for helping build **satiscode**:
 
 # Copy atributions
 This tool uses librarys and executables from the `clangd` util by `LLVM`, `PyRight` by `microsoft`. to see the copy atributions [please click here](NOTICES.md)
+
+# Packages
+See the repository's `packages/` directory for packages included with Satiscode. These packages are also published on npmjs.
+| Name | Readme link |
+|---|---|
+| FIXSON | [FIXSON-LSP JSON LSP](packages/FIXSON-LSP/README.md) |
+| FIXML | [FIXML-LSP XML LSP](packages/FIXML-LSP/README.md) |

USAGE.md

@@ -0,0 +1,75 @@
+# Using Satiscode
+
+This guide covers the main features in the Satiscode Windows desktop editor. For development setup, see [README.md](README.md) and [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Install and start
+
+Download the latest Windows installer from the [Satiscode releases page](https://github.com/gtref/satiscode/releases/latest), run it, and launch Satiscode from the Start menu or desktop shortcut.
+
+Satiscode runs on Windows 10 or newer. Python must be installed for Python language services to work. Node.js 20 or newer is only needed if you are running Satiscode from a source checkout.
+
+## Open and edit files
+
+- Select **Open** or press `Ctrl+O` to open a file.
+- Select **Open Folder** or press `Ctrl+K` to open a workspace folder. Use the Explorer sidebar to browse and open files in that folder.
+- Select **New** or press `Ctrl+N` to create an untitled tab. Use **Save** (`Ctrl+S`) to save it for the first time, or **Save As** (`Ctrl+Shift+S`) to choose a new path for an existing file.
+- Switch between open files using the tabs. The **+** button creates another tab. Close a tab with its close button or middle-click it. If a tab has unsaved changes, Satiscode asks whether to save or discard them before closing.
+
+The editor marks unsaved changes in the tab. Save your work before exiting or closing a tab.
+
+## Language support
+
+Satiscode normally selects the editor language from the file extension. Use the language selector in the toolbar to override it for the active file, or choose **Auto** to return to automatic selection.
+
+| Files | Language support |
+| --- | --- |
+| C/C++: `.c`, `.cc`, `.cpp`, `.cxx`, `.h`, `.hh`, `.hpp`, `.hxx` | clangd diagnostics, completion, hover information, and go-to-definition |
+| Python: `.py` | Pyright diagnostics, completion, hover information, and go-to-definition |
+| JSON: `.json` | FIXSON diagnostics, completion, and hover information |
+| JSONC: `.jsonc` | Monaco editor support; strict FIXSON validation is not started |
+| XML: `.xml`, `.xsd`, `.xsl`, `.xslt`, `.svg`, `.plist` | FIXML diagnostics, element completion, and hover information |
+| JavaScript/JSX, TypeScript/TSX, HTML, CSS/SCSS | Monaco syntax editing support |
+| Markdown: `.md`, `.markdown` | Preview and edit modes |
+| Other files | Plain-text editing |
+
+Language services report diagnostics in the **Problems** panel. Press `Ctrl+.` to show or hide it; select a problem to jump to its location. The C/C++, Python, JSON, and XML language servers provide the services listed above. If a language server is unavailable, Satiscode can still open and edit the file, but that server's diagnostics and code intelligence will not be available.
+
+For Markdown files, use **Preview** and **Edit** above the document to switch between the rendered preview and source text. Preview updates from the open document's current contents.
+
+## Search and navigation
+
+Press `Ctrl+F` or select **Find** to search within the active file. Use the previous and next controls to move between matches. For supported language servers, hover over symbols for details, request completion while typing, or use go-to-definition to navigate to a declaration.
+
+## Git
+
+Open a folder first, then select **Source Control** in the activity bar to view its Git status and recent commits. Git must be installed and available on your system.
+
+- Select **Refresh** to reload repository status.
+- Select **Stage all** to stage all changes in the workspace.
+- Enter a commit message and select **Commit** to commit the staged changes.
+- Select **Pull** or **Push** to synchronize with the configured remote. Your Git remote and authentication must already be set up.
+- If the folder is not yet a repository, select **Init repository** to initialize one.
+
+To see line-by-line history for a saved file, open it and select **Blame**. The file must be inside the currently open Git workspace.
+
+## Appearance and interface language
+
+Choose **Dark Theme**, **Light Theme**, or **High Contrast** from the theme selector. Use the language button in the toolbar to switch the interface between English and Spanish. These preferences are saved.
+
+## Keyboard shortcuts
+
+| Shortcut | Action |
+| --- | --- |
+| `Ctrl+N` | Create a new tab |
+| `Ctrl+O` | Open a file |
+| `Ctrl+K` | Open a folder |
+| `Ctrl+S` | Save the active file |
+| `Ctrl+Shift+S` | Save the active file as a new file |
+| `Ctrl+F` | Find in the active file |
+| `Ctrl+.` | Toggle the Problems panel |
+
+## Troubleshooting
+
+- **A language server is unavailable:** Check the language status in the toolbar. Python language services require Python to be installed. A clean source checkout may not include the clangd or Pyright server files; see the development notes in [README.md](README.md).
+- **Git actions fail:** Confirm Git is installed and available on your system. For Push and Pull, check that the repository has a remote and that your Git credentials are configured.
+- **A file has no diagnostics:** Confirm the correct language is selected and that the relevant language server is available. JSONC files use Monaco support without FIXSON diagnostics.