chore(docs): Add doc files and wiki-sync-workflow in the repo for easy wiki edit

2026-07-28 08:01:19 -07:00 · 2026-01-19 21:27:47 +05:30
parent 0d5a0a783c
commit 773b20112d
3 changed files with 268 additions and 0 deletions
@@ -0,0 +1,29 @@
+name: Sync Docs to Wiki
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - .github/workflows/wiki-sync.yml
+
+concurrency:
+  group: publish-wiki
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+
+jobs:
+  update-wiki:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v6
+
+      - name: Push to Wiki
+        uses: Andrew-Chen-Wang/github-wiki-action@v4
+        with:
+          path: docs
+          token: ${{ secrets.WIKI_SYNC_PAT_TOKEN }}
+          commit_message: "Sync docs from main repo: ${{ github.event.head_commit.message }}"
@@ -0,0 +1,28 @@
+# Welcome to the PicoForge Wiki
+
+**PicoForge** is a modern desktop application for configuring and managing **Pico FIDO** security keys. Built with Rust, Tauri, and Svelte, it provides an intuitive interface for:
+
+- Reading device information and firmware details
+- Configuring USB VID/PID and product names
+- Adjusting LED settings (GPIO, brightness, driver)
+- Managing security features (secure boot, firmware locking) (WIP)
+- Real-time system logging and diagnostics
+- Support for multiple hardware variants and vendors
+
+## Documentation Index
+
+### Getting Started
+*   **[Installation](Installation)** – Detailed setup instructions for all supported operating systems (Windows, macOS, Linux).
+*   **[First Setup](First-Setup)** – How to initialize and personalize your new Pico-Key.
+
+### User Guide
+*   **[Device Management](Device-Management)** – configuring PINs, resetting the device, and firmware updates.
+*   **[Troubleshooting](Troubleshooting)** – Solutions for common connection and detection issues.
+*   **[FAQ](FAQ)** – Frequently asked questions about PicoForge and Pico-Key.
+
+### Development
+*   **[Building from Source](Building)** – Instructions for compiling PicoForge locally.
+*   **[Contributing](Contributing)** – Guidelines for reporting bugs and submitting code changes.
+
+---
+*Return to the [LibreKeys PicoForge Repository](https://github.com/librekeys/picoforge)*
@@ -0,0 +1,211 @@
+Welcome to the official installation guide for PicoForge. This document will help you set up the application on your operating system.
+
+## Windows
+
+1.  #### Download the Installer
+
+    Go to the [Latest Releases](https://github.com/librekeys/picoforge/releases/latest) page and download the `picoforge_[version]_[arch]-setup.exe` file.
+
+2.  #### Run the Installer
+
+    Locate the downloaded file and run it to install the application.
+
+3.  #### Verify Smart Card Service
+
+    For the application to communicate with your device, the Windows Smart Card service must be running. You can ensure this by running the following command in PowerShell:
+
+    ```powershell
+    Get-Service SCardSvr | Start-Service
+    ```
+
+> [!IMPORTANT]
+> Please run the application as **Administrator**. This is often required for the application to correctly detect and interact with the hardware device.
+
+## macOS
+
+> [!WARNING]
+> The macOS version of this application is tested rarely, while it does work fine, it might have some bugs that I have not experienced, feel free to report it on issues.
+> 
+> If you are a developer or user who can assist with testing and debugging on macOS, contributions are highly appreciated. Please check the Issues tab or join our Discord server.
+
+#### Setup Instructions:
+
+- Download the application from the [Latest Releases](https://github.com/librekeys/picoforge/releases/latest).
+- No additional driver setup is usually required as the PC/SC framework is built into macOS.
+
+## Linux
+
+We offer multiple ways to run the application on Linux. Please choose the method that best suits your needs.
+
+### Global Prerequisite: Smart Card Daemon
+
+Regardless of the installation method you choose below, your **host operating system** must have the Smart Card Daemon (`pcscd`) installed and running. This service allows the application to talk to the USB device.
+
+#### Enable pcscd on your host:
+
+```bash
+# Command may vary by distro, commonly:
+sudo systemctl enable --now pcscd
+```
+
+### Option 1: [COPR Repository](https://copr.fedorainfracloud.org/coprs/lockedmutex/picoforge/) (Recommended for Fedora, openSUSE, and RHEL-based distros)
+
+[COPR](https://copr.fedorainfracloud.org/coprs/lockedmutex/picoforge/) is the recommended way of installing the application on Fedora, openSUSE, and RHEL-based distributions. This method ensures you get the latest release of the app on the same day it's published.
+
+#### Fedora
+
+##### Fedora Rawhide, 43, 42
+
+```bash
+sudo dnf copr enable lockedmutex/picoforge
+sudo dnf install picoforge
+```
+
+#### RHEL-based Distributions
+
+##### RHEL, CentOS, AlmaLinux, Rocky Linux (EPEL 10)
+
+```bash
+sudo dnf install dnf-plugins-core
+sudo dnf copr enable lockedmutex/picoforge
+sudo dnf install picoforge
+```
+
+#### openSUSE
+
+##### Tumbleweed
+
+```bash
+sudo zypper addrepo https://copr.fedorainfracloud.org/coprs/lockedmutex/picoforge/repo/opensuse-tumbleweed/lockedmutex-picoforge-opensuse-tumbleweed.repo
+sudo zypper refresh
+sudo zypper install picoforge
+```
+
+##### Leap 15.6
+
+```bash
+sudo zypper addrepo https://copr.fedorainfracloud.org/coprs/lockedmutex/picoforge/repo/opensuse-leap-15.6/lockedmutex-picoforge-opensuse-leap-15.6.repo
+sudo zypper refresh
+sudo zypper install picoforge
+```
+
+#### Post-Installation
+
+After installation, you can launch picoforge from your application menu or run:
+
+```bash
+picoforge
+```
+
+#### Troubleshooting
+
+If you encounter issues during installation:
+
+- **Fedora/RHEL**: Ensure EPEL repository is enabled for RHEL-based systems
+- **openSUSE**: Verify the repository URL matches your distribution version
+- For general issues, check the [project repository](https://github.com/librekeys/picoforge) or [report a bug](https://github.com/librekeys/picoforge/issues)
+
+### Option 2: AppImage (Simplest)
+
+The AppImage format contains most dependencies and runs on almost any Linux distribution.
+
+1.  Download the `.AppImage` file from the [Latest Releases](https://github.com/librekeys/picoforge/releases/latest).
+2.  Mark the file as executable:
+    ```bash
+    chmod +x picoforge_*.AppImage
+    ```
+3.  Launch the file.
+
+> [!NOTE]
+> If the AppImage does not start, check if you are missing FUSE (Filesystem in Userspace), which is required for AppImages on some newer distributions like Ubuntu 22.04+.
+
+### Option 3: Distrobox
+
+If you encounter dependency issues on your specific distribution, we highly recommend using **Distrobox**. This method runs the application inside a stable Fedora environment while integrating it seamlessly with your desktop.
+
+#### Requirements:
+
+- [Distrobox](https://distrobox.it/) installed on your system.
+- A container engine like `podman` or `docker`.
+
+#### Step-by-Step Guide:
+
+1.  **Create the Container:**
+    We will use a standard Fedora Toolbox image which is known to be compatible.
+    ```bash
+    distrobox create -i quay.io/fedora/fedora-toolbox:43 -n picoforge
+    ```
+
+2.  **Enter the Container:**
+    ```bash
+    distrobox enter picoforge
+    ```
+
+3.  **Install the Application:**
+    ```bash
+    sudo dnf copr enable lockedmutex/picoforge
+    sudo dnf install picoforge
+    ```
+
+4.  **Export to Host System:**
+    This step creates a shortcut in your system's application menu so you can launch it like any other app.
+    ```bash
+    distrobox-export --app picoforge
+    ```
+
+5.  **Launch:**
+    You can now find and launch "picoforge" from your application launcher.
+
+### Option 4: Native Package
+
+If you prefer to install the package directly on your system, please ensure you have installed all necessary dependencies for your specific distribution.
+
+<details>
+<summary><strong>OpenSuse Tumbleweed Dependencies</strong></summary>
+
+```bash
+sudo zypper install libwebkit2gtk-4_1-0 libsoup-3_0-0 libgtk-3-0 \
+libpcsclite1 libhidapi-hidraw0 libsecret-1-0 \
+gstreamer-plugins-base libavif16 libwebp7 libenchant-2-2 pcsc-tools
+
+sudo systemctl enable --now pcscd
+```
+</details>
+
+<details>
+<summary><strong>Fedora Dependencies</strong></summary>
+
+```bash
+sudo dnf install webkit2gtk4.1 libsoup3 gtk3 \
+pcsc-lite pcsc-tools hidapi libsecret \
+gstreamer1-plugins-base libavif libwebp enchant2
+
+sudo systemctl enable --now pcscd
+```
+</details>
+
+<details>
+<summary><strong>Debian / Ubuntu Dependencies</strong></summary>
+
+```bash
+sudo apt update
+sudo apt install libwebkit2gtk-4.1-0 libgtk-3-0 libsoup-3.0-0 \
+libpcsclite1 pcscd pcsc-tools libhidapi-hidraw0 libsecret-1-0 \
+gstreamer1.0-plugins-base libavif16 libwebp7 libenchant-2-2
+```
+</details>
+
+<details>
+<summary><strong>Arch Linux Dependencies</strong></summary>
+
+```bash
+sudo pacman -S webkit2gtk-4.1 gtk3 libsoup3 \
+pcsclite pcsc-tools hidapi libsecret \
+gst-plugins-base libavif libwebp enchant
+```
+</details>
+
+#### Installation:
+
+1.  Download the `.deb` (Debian/Ubuntu) or `.rpm` (Fedora/Suse) from the releases.
+2.  Install using your package manager (e.g., `sudo apt install ./package.deb` or `sudo dnf install ./package.rpm`) or a software center like `gnome-software`.