From 0a0559824a3e60c722e3b3517a504f778950f790 Mon Sep 17 00:00:00 2001 From: bbenligiray Date: Wed, 6 Aug 2025 19:01:29 +0300 Subject: [PATCH] Redirect to hinter.net for instructions --- README.md | 32 ++---------- hinter-helper.md | 129 ----------------------------------------------- instructions.md | 43 ---------------- 3 files changed, 4 insertions(+), 200 deletions(-) delete mode 100644 hinter-helper.md delete mode 100644 instructions.md diff --git a/README.md b/README.md index bc53a1e..cb867e5 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,6 @@ -# `hinter-cline` +# hinter-cline -- **Hinters** collect intelligence, compose personalized reports for other hinters, and exchange these reports using [`hinter-core`.](https://github.com/bbenligiray/hinter-core) -- **`hinter-cline`** is an AI-assisted environment that hinters use as a companion to [`hinter-core`](https://github.com/bbenligiray/hinter-core) to process information and compose reports. +- **Hinters** collect intelligence, compose personalized reports for other hinters, and exchange these reports using [hinter-core.](https://github.com/bbenligiray/hinter-core) +- **hinter-cline** is an AI-assisted environment that hinters use as a companion to hinter-core to process information and compose reports. -See [instructions](./instructions.md) to run `hinter-cline` in a Docker container. - -## Features - -`hinter-cline` wraps two solutions in a Docker container for portability and security: - -- [`code-server`,](https://github.com/coder/code-server) an enhanced fork of VS Code that you can use through your browser -- [Cline,](https://github.com/cline/cline) a coding assistant for VS Code - -### `hinter-helper` - -In addition, `hinter-cline` includes [`hinter-helper`,](./hinter-helper.md) an interactive CLI tool that facilitates some hinter workflows. - -Its features include: - -- Managing peers (add, edit, remove) -- Organizing peers into groups -- Creating and posting flexible report drafts to peers and groups - -## `hinter-core-data/` additions - -`hinter-cline` extends the [`hinter-core-data/` structure of `hinter-core`](https://github.com/bbenligiray/hinter-core?tab=readme-ov-file#hinter-core-data) by adding: - -- `entries/`: A directory for your private knowledge base, including outgoing report drafts. -- `.git/`:A [Git](https://git-scm.com/) directory containing the `hinter-core-data/` version history. +See https://hinter.net/ for more information about hinter-cline. diff --git a/hinter-helper.md b/hinter-helper.md deleted file mode 100644 index 856ac0d..0000000 --- a/hinter-helper.md +++ /dev/null @@ -1,129 +0,0 @@ -# `hinter-helper` CLI Tool - -`hinter-helper` is an interactive command-line tool for managing peers, groups, and report drafts according to `hinter-cline` conventions. - -## Running the Tool - -Run `hinter-helper` using: - -```sh -npm start -``` - -You will be presented with a menu of options. - -## Menu Options - -1. **Create a report draft:** Interactively helps you create a new report draft. - It prompts for a title and lets you select recipients from a list of known peers and groups. -2. **Sync reports:** Scans the `entries/` directory for all report drafts and synchronizes them with the appropriate peers. - This ensures that each peer's `outgoing` directory perfectly reflects the reports they are meant to receive, adding new ones and removing any that are no longer targeted at them. -3. **Add a peer:** Guides you through adding a new peer by asking for a unique alias and their 64-character public key. -4. **Manage a peer:** Lets you select a peer to update their alias or public key, or to delete them entirely. -5. **Add a group:** Guides you through creating a new group and adding existing peers to it. -6. **Manage a group:** Lets you select an existing group to add or remove peers from it. -7. **Exit:** Closes the tool. - -## Peer Groups - -You can organize peers into groups to make sending reports to multiple peers easier. -A peer can belong to any number of groups. -The tool manages group memberships by adding a `groups` array to the `hinter-cline` object within each peer's `hinter.config.json` file. - -### Example `hinter.config.json` - -Here is an example of what a peer's configuration file looks like when they belong to two groups: - -```json -{ - "publicKey": "a1b2c3d4...", - "hinter-cline": { - "groups": ["my-friends", "work-colleagues"] - } -} -``` - -## Report Draft Frontmatter - -The core of the reporting system is the YAML frontmatter at the top of each report draft file. -When you create a draft, the `to` and `except` fields are populated interactively, while `sourcePath` and `destinationPath` are left empty for you to fill in. - -### Example: Sending a Markdown Report - -This is the most common use case, where the body of the draft file itself is sent as the report. -If `sourcePath` and `destinationPath` are empty, they default to the relative path of the draft file. - -```yaml ---- -to: ["peer-alias-1", "group:my-friends"] -# Say peer-alias-3 is a member of my-friends and we don't want them to receive the report -except: ["peer-alias-3"] -# sourcePath is empty, so the body of this file is sent. -sourcePath: "" -# destinationPath is empty, so it defaults to the draft's path. -# If this draft is at "entries/foo/my-report.md", the destinations will be peers/*/outgoing/foo/my-report.md -destinationPath: "" ---- -# My First Report - -This is the content that will be sent to the peers. -The frontmatter above will be stripped out automatically. -``` - -### Example: Sending a Separate File - -You can also use a draft as a "control file" to send other file types, like images or archives. - -```yaml ---- -to: ["peer-alias-2"] -except: [] -# sourcePath points to the image we want to send. -sourcePath: "./images/diagram.png" -# The image will be saved to peers/peer-alias-2/outgoing/images/diagram.png on the peer's machine. -destinationPath: "" ---- -# Control file for sending diagram.png - -This body text will be ignored, because sourcePath is not empty. -``` - -### Example: Sending a Directory - -You can also send an entire directory. -The directory structure will be preserved at the destination. - -```yaml ---- -to: ["peer-alias-1"] -except: [] -# sourcePath points to the directory we want to send. -sourcePath: "./meme-folder" -# The contents of my-album will be saved to peers/peer-alias-1/outgoing/meme-folder -destinationPath: "" ---- -``` - -### Key Fields Explained - -- `to`: A list of recipients. - Can contain individual peer aliases (e.g., `"peer-1"`) and groups (e.g., `"group:friends"`). - If this array is empty, the report will not be sent to anyone. -- `except`: An array of peers or groups to exclude from the recipients. -- `sourcePath`: (Optional) The path to the file or directory to be sent, relative to the draft file. - If left empty, the body of the draft itself (with frontmatter removed) is sent. -- `destinationPath`: (Optional) The destination path for the file or directory in the peer's `outgoing` directory. - If left empty, it defaults to the name of the source file or directory. - -### Important Rules - -- **Validation:** The `syncReports` command is strict and will stop immediately if it encounters any of the following issues in a draft: - - The YAML frontmatter is malformed. - - The `to` or `except` fields are missing. - - A peer or group listed in `to` or `except` does not exist. - - The file specified in `sourcePath` cannot be found. -- **Synchronization:** The sync process is not additive. - It ensures that a peer's `outgoing` directory is an exact mirror of the reports they should receive. - - **Adds/Updates:** New or changed reports are written to the `outgoing` directory. - - **Deletes:** Reports that were previously sent but are no longer targeted at a peer (e.g., the draft was deleted or the peer was removed from the `to` list) will be deleted from their `outgoing` directory. -- **YAML Stripping:** When the content of the draft file itself is being sent (i.e., `sourcePath` is empty), its YAML frontmatter is automatically removed. If an external Markdown file is specified in `sourcePath`, it is sent as-is, with its frontmatter intact. diff --git a/instructions.md b/instructions.md deleted file mode 100644 index 0688290..0000000 --- a/instructions.md +++ /dev/null @@ -1,43 +0,0 @@ -# Instructions - -This project is designed to work across all operating systems and be accessible to non-technical users. - -## Installation - -1. [Install `hinter-core` and run it in always restart mode.](https://github.com/bbenligiray/hinter-core/blob/main/instructions.md) - -2. (OPTIONAL) The technically inclined may choose to build the Docker image locally. - -3. Start `hinter-cline` in always restart mode using: - - ```sh - docker run -d --name my-hinter-cline --restart=always -p8080:8080 -v"$(pwd)/hinter-core-data":/hinter-cline/hinter-core-data bbenligiray/hinter-cline:0.0.1 - ``` - -4. Open your browser and navigate to [`localhost:8080`](http://localhost:8080) to see the VS Code interface. - Since `hinter-cline` is running in always restart mode, VS Code will always be available at `localhost:8080`, even after you restart your machine. - -5. Click the Cline icon on the VS Code sidebar. - Select an API provider and enter your API key. - - If you are not a paid subscriber to any of these API providers, consider using one that offers a free trial for testing. - For example: - - Create an [OpenRouter](https://openrouter.ai/) account - - Create an API key - - Configure Cline to use [`deepseek/deepseek-chat-v3-0324:free`](https://openrouter.ai/deepseek/deepseek-chat-v3-0324:free) - -## Working with Cline - -There are two important concepts to know about Cline: - -### Plan/Act toggle button - -You can chat with Cline about the contents of your repo in Plan Mode. -For Cline to make changes (for example, to help you write a report draft), you will need to switch to Act Mode. -Switching between Plan and Act Mode retains the context, so you will likely want to switch between the two during use. - -### Tasks - -Whenever you want Cline to start as a clean slate, start a new task (for example, by clicking the plus sign on the Cline extension). -Doing this between independent hinter workflows will cause Cline to perform in a more consistent manner. -However, you may want to continue using the same task for dependent workflows, such as revising the same report multiple times.