# (docs/hinter-net/introduction.md)

![Hinter Net Social Card](../../static/img/hinter-net-social-card.jpg)

**Hinter Net** is a peer-to-peer network for collaborative intelligence, designed to scale human networking and collaboration beyond their natural limits.
By combining a secure, decentralized communication protocol with powerful AI assistance, it enables users—called **hinters**—to build high-trust, private networks.
These networks allow for sharing and contextualizing sensitive information and mapping reputation of relevant actors at a superhuman scale.

This AI-augmented networking experience is delivered through two core applications, which provide the foundational tools for you to build and leverage your own intelligence network:

- **[hinter-core](../hinter-core/introduction.md)**: Powers the secure, peer-to-peer exchange of reports.
- **[hinter-cline](../hinter-cline/introduction.md)**: Serves as the AI-assisted command center for processing intelligence and composing reports.

:::tip Don't Read, Chat!

You can copy-paste [`llms-full.txt`](https://hinter.net/llms-full.txt) to your preferred AI.

:::

# Use Cases (docs/hinter-net/use-cases.md)

The concepts behind Hinter Net can be applied to a wide variety of scenarios where high-trust collaboration and information asymmetry are valuable.
Here are a few examples to illustrate how different professionals might use the platform.

## For Venture Capitalists & Investors

A small group of VCs specializing in a niche sector can form a network to share proprietary deal flow and due diligence.

- **Collection**: Each investor maintains private entries on promising founders, interesting projects, and notes from pitch meetings.
- **Exchange**: When a new company emerges, they can securely share their private diligence notes, technical assessments, and opinions on the founding team.
  An AI assistant can help synthesize these disparate reports into a single, comprehensive overview.
- **Reputation**: An investor who consistently sources high-quality deals or provides insightful analysis builds a strong reputation.
  This enhances their ability to influence the group's collective opinion and guide investment decisions.

## For Business Development & Sales Teams

A distributed business development team can use Hinter Net to manage relationships and coordinate outreach without relying on a centralized CRM.

- **Collection**: Each team member keeps a personal wiki of their contacts, meeting notes, and key information about partner companies.
- **Exchange**: Before a major conference, team members can exchange reports on who they plan to meet and what their goals are.
  The AI assistant can identify overlapping contacts or potential introductions.
  If one member has a strong relationship with a target company, they can provide a warm introduction for a colleague.
- **Reputation**: A team member with a strong reputation for valuable intelligence and key introductions can attract new career opportunities or parallel engagements, creating a feedback loop that enriches their original project.

## For Community & DAO Management

A group of core contributors in a DAO can use Hinter Net to track community sentiment, identify key contributors, and coordinate governance proposals.

- **Collection**: Each manager tracks conversations, identifies influential community members, and documents potential issues in their private wiki.
- **Exchange**: They can share weekly summaries of community sentiment, flag potential FUD campaigns, and co-author governance proposals in a private, secure environment before presenting them to the public.
- **Reputation**: A contributor who accurately gauges community sentiment or drafts successful proposals becomes a trusted thought leader within the DAO's inner circle.

## The Compounding Effect of Reputation

The true power of Hinter Net is its holistic reputation system.
The trust you build in one context—whether social or professional—compounds, enhancing your influence and opportunities across all your networks.
This dynamic makes you a more effective and influential node while simultaneously strengthening the entire ecosystem.

For example:

- A **VC** who builds a strong reputation for insightful diligence can leverage that trust to get honest, off-the-record feedback on a new DAO governance proposal they are interested in.
- A **Community Manager** known for accurately gauging sentiment can use that credibility to make a valuable introduction for a portfolio company of a VC in their network.
- A **Developer** who is a trusted contributor to an open-source project can leverage that technical reputation to get a warm introduction to an investor for their own startup idea.

## An Untapped Use Case for AI: Networking

For the individual, AI's primary value lies in augmenting our ability to enact personal agency in the world.
It's a tool to compensate for our weaknesses and enhance our strengths.
For example, a talented developer would gain more value from using AI to manage their professional network than from assistance with coding—a skill they have already mastered.

This need for better networking isn't unique to developers; it addresses a fundamental challenge of modern life that everyone faces.
Meaningful networking requires us to pay attention to one another.
Yet, the digital systems we use are often designed to capture and monetize our attention, distracting and isolating us as a means of control.
We all feel the strain of being manipulated at scale, which makes genuine connection harder to achieve.

Hinter Net confronts this modern issue with modern means.
It is designed to help you redirect your focus to your own high-trust network, directly challenging the centralized forces that seek to stifle collaboration at the level of the individual.

import Tabs from '@theme/Tabs'; (docs/hinter-net/quickstart.mdx)
import TabItem from '@theme/TabItem';

# Quickstart

This guide will walk you through installing hinter-core and hinter-cline and connecting to your first peer. 
hinter-core runs natively on your machine, enabling it to manage peer-to-peer connections by accessing your network interface directly.
hinter-cline runs inside a Docker container, providing a standardized user environment and sandboxing the AI assistant as a security best practice.

## Prerequisites

- [Node.js](https://nodejs.org/) (v22 or later) installed.
- [pm2](https://pm2.keymetrics.io/) installed with the following command.
  ```sh
  npm install -g pm2
  ```
- hinter-core installed with the following command.
  ```sh
  npm install -g @hinter-net/hinter-core@0.2.1
  ```
- [Docker Desktop](https://docs.docker.com/desktop/) installed and running.

:::tip Verify `@hinter-net/hinter-core` Integrity

  Verify the integrity of the `@hinter-net/hinter-core` package by checking its [provenance on npmjs.com](https://www.npmjs.com/package/@hinter-net/hinter-core).
  This shows it was built and published by Github Actions as described in the source repository.

:::

## Step 1: Run hinter-core

hinter-core is the networking engine.
It needs to be running in the background to send and receive reports.

1.  **Initialize Your Data Directory & Keypair**

    Open a terminal and run the following command.

    ```sh
    hinter-core-initialize
    ```

    This creates a `hinter-core-data/` directory in your home directory, which will store all your data and your unique cryptographic keypair.

2.  **Start hinter-core in the Background**

    Start hinter-core using pm2.

    ```sh
    pm2 start hinter-core --name my-hinter-core
    ```

    :::tip Check Your Logs
    You won't see hinter-core output because it's running in the background, but you can check its logs anytime with:

    ```sh
    pm2 logs my-hinter-core
    ```

    :::

    Save a snapshot of the apps that pm2 is currently running (in this case, only hinter-core).

    ```sh
    pm2 save
    ```

    Generate a startup script that will restore the snapshot you just took.

    ```sh
    pm2 startup
    ```

    Finally, run the command printed by `pm2 startup` to configure the startup script to run when your machine starts.

## Step 2: Run hinter-cline

hinter-cline is your command center, providing a VS Code interface in your browser.
It comes with Cline, an AI assistant extension for VS Code.

1.  **Start hinter-cline in the Background**

    Run this command to start the hinter-cline container.
    It's set to always restart, so it will launch automatically even after you restart your computer.

    <Tabs groupId="operating-systems">
    <TabItem value="linux" label="Linux/macOS/WSL2" default>
    ```sh
    docker run -d --name my-hinter-cline --restart=always --user $(id -u):$(id -g) -p 8080:8080 -v"$(node -p "require('os').homedir()")/hinter-core-data:/hinter-cline/hinter-core-data" bbenligiray/hinter-cline:0.2.5
    ```
    </TabItem>
    <TabItem value="windows" label="Windows">
    ```sh
    docker run -d --name my-hinter-cline --restart=always -p 8080:8080 -v"$(node -p 'require(\"os\").homedir()')/hinter-core-data:/hinter-cline/hinter-core-data" bbenligiray/hinter-cline:0.2.5
    ```
    </TabItem>
    </Tabs>

    :::tip Do not use Command Prompt on Windows
    Use PowerShell or WSL CLI, and not the Command Prompt (CMD) on Windows.
    For example, the terminal in Docker Desktop uses PowerShell by default and is suitable to run these commands.
    :::

    This starts the hinter-cline container and makes it accessible on port `8080`.
    It shares the `hinter-core-data/` directory with hinter-core, so it can access your peers and reports.

2.  **Open hinter-cline in Your Browser**

    Navigate to [`http://localhost:8080`](http://localhost:8080).
    You should see the VS Code interface.

3.  **Configure Cline**
    - Click the Cline icon in the VS Code sidebar.
    - Select an AI provider and enter your API key.

      :::tip Free OpenRouter Models for Testing
      If you don't have a subscription to an AI provider, you can get a key from [OpenRouter](https://openrouter.ai/) and start testing with one of the free models such as [`deepseek/deepseek-chat-v3-0324:free`](https://openrouter.ai/deepseek/deepseek-chat-v3-0324:free).
      :::

## Step 3: Add Your First Peer

Now you're ready to connect with a peer.
You'll need their 64-character public key.

:::tip Find Your First Peer
If you don't know anyone to connect with, check out the **[Get Involved](./get-involved.md)** page for tips on how to find your first peers.
:::

1.  **Open a Terminal in hinter-cline**

    In the browser-based VS Code interface, go to the "Terminal" menu and select "New Terminal".

2.  **Run the helper**

    In the new terminal panel, type the following command to start the helper tool:

    ```sh
    npm start
    ```

3.  **Add a Peer**
    - Select the "Add a peer" option from the menu.
    - Follow the prompts to enter a unique alias (a nickname) for your peer and paste their public key.

## Step 4: Share Your Public Key

Your peer needs to add you back!

1.  **Find Your Public Key**

    Your key is in the `hinter-core-data/.env` file.
    You can see it in the VS Code file explorer.
    The file will look like this:

    ```
    PUBLIC_KEY=...
    SECRET_KEY=...
    ```

    Copy the entire `PUBLIC_KEY` value.

    :::warning Protect Your Secret Key
    Never share your `SECRET_KEY` with anyone.
    Sharing it would allow others to impersonate you on the network.
    :::

2.  **Send It to Your Peer**

    Share your public key with your peer.
    Once they add you using the same steps above, you'll be connected!

## Step 5: Send Your First Report

Now that you're connected, you can send your first report.
This is a two-step process.

1.  **Create a Report Draft**
    - In the hinter-cline terminal, run `npm start` to launch the helper.
    - Select the "Create a report draft" option.
    - Give your report a title.
    - When prompted to select recipients, choose the alias of the peer you just added.
    - A new Markdown file will be created in your `entries/` directory. Add your content to this file and save it.

2.  **Sync and Send the Report**
    - Go back to the main menu of the helper tool.
    - Select the "Sync reports" option.

    This command detects your draft, prepares it by removing its frontmatter (the header enclosed by `---`), and hands it off to hinter-core, which sends it to your peer.
    That's it!

## What's Next?

You've successfully set up your node and exchanged your first piece of intelligence!

To dive deeper, check out the user guides:

- **[hinter-core User Guide](../hinter-core/user-guide/hinter-core-data)**
- **[hinter-cline User Guide](../hinter-cline/user-guide.md)**

# Curate Intelligence (docs/hinter-net/core-concepts/curate-intelligence.md)

The foundation of any effective intelligence work is a systematic approach to collecting and curating information.
In Hinter Net, your private knowledge base is your primary asset.
This is your personal, private wiki—a living repository of your knowledge.

## Build Your Personal Wiki

Think of your knowledge base as a digital garden.
It's a space where you cultivate knowledge over time, a collection of interconnected notes that you can continuously edit, refine, and link together with the help of your AI assistant.

- **Create Topic-based Entries**: Create pages for people, projects, companies, or concepts that are important to you.
- **Edit and Refine**: As you learn more, update your entries. Your knowledge base should evolve with your understanding.
- **Interlink Your Notes**: Hyperlink related ideas to create a rich, contextual web of information that both you and your AI assistant can later navigate.

## Index Peer Intelligence

Your private knowledge base isn't limited to your own writings. To truly leverage your network, you should also index important or seminal reports you receive from your peers.
By cataloging these reports, you make them discoverable by your AI assistant. This allows the assistant to draw upon the collective intelligence of your network, incorporating insights from your most trusted peers into its analysis and synthesis for future tasks.

## A Foundation for Synthesis

By treating your knowledge base as a personal wiki, you create a powerful foundation for AI-driven synthesis.
When you ask your AI assistant to draft a report or summarize a topic, it can draw from a rich, interconnected set of curated documents.
The output doesn't have to be a formal Hinter Net report; the assistant can just as easily generate a draft for a regular email or a simple message based on the information it finds in your knowledge base.

# Exchange Reports (docs/hinter-net/core-concepts/exchange-reports.md)

Collecting intelligence is only the first step.
The true power of Hinter Net is unlocked once you start exchanging tailored, contextualized reports with specific individuals in your trusted network.

## From Intelligence to Action

Using your curated personal wiki and the AI assistance of hinter-cline, you can craft reports that are relevant and valuable to your peers.
This could be:

- A speculative analysis on a stealth startup that just raised a seed round.
- A catalog of persons of interest, mapping out potential warm contact points for future opportunities.
- A disclosure of a potential exploit in a widely-used protocol.
- A curated "meme folder" that captures the evolving culture and in-jokes of a specific online community.

The hinter-core protocol handles the secure, peer-to-peer exchange of these reports, ensuring they are delivered directly and privately.

## Creating Value Through Emergence

Every report you send contributes to a shared pool of knowledge.
The goal is not always to provide immediately actionable intelligence.
Instead, it's an investment in serendipity.
Information that seems minor today might be the missing piece of a puzzle for a peer tomorrow, or it might combine with other reports to reveal an unexpected opportunity a month from now.
By building a rich, long-term history of shared context, you and your peers create the conditions for uncovering surprising, high-value insights that would never have emerged in isolation.
The core purpose of Hinter Net is to cultivate this emergent potential.

# Build a Reputation Network (docs/hinter-net/core-concepts/reputation-network.md)

The ultimate goal of Hinter Net is to build a reputation network by cultivating a high-trust inner circle where genuine connection and collaboration can flourish on a foundation of authenticity and mutual respect.

## The Foundation of Trust

In a world saturated with noise, trust is earned through careful attention.
Every interaction within your network is an opportunity to understand your peers on a deeper level.
The goal is to genuinely listen and discern who offers a clear signal amidst the noise, appreciating the unique insights, integrity, and value they bring.

By privately documenting your observations, you engage in a mindful practice of paying attention, building a personal understanding of your network's strengths.
This allows you to build relationships on a solid foundation of evidence-based trust, enabling you to collaborate with confidence when it matters most.

This evidence-based approach is also what allows the network to scale.
You can share these documented records with trusted peers, allowing them to form their own nuanced interpretations of the reputation map with the help of AI assistance.
This system is designed to scale trust itself, enabling a larger community to benefit from high-fidelity, shared understanding.

## From Reputation to Meaningful Collaboration

A strong reputation, built on a foundation of authentic contributions and reliability, naturally fosters deeper collaboration.
When you have a proven track record of providing valuable insights and acting with integrity, your perspective is respected, your recommendations are considered, and your efforts are supported.

This creates a powerful, positive feedback loop.
The more you contribute to the health of the network, the more you are trusted by the people who matter to you.
This is how Hinter Net helps you form a true inner circle: a small, supportive group of peers who can rely on each other to navigate complex challenges and create new opportunities together.

# Design Philosophy (docs/hinter-net/design-philosophy.md)

For Hinter Net to reach its full potential, you must be able to trust it with your most sensitive information.
This level of trust is fundamentally incompatible with proprietary and centralized communication and AI solutions that are meant to power surveillance-based business models.

Hinter Net is built on the core principle of end-to-end user sovereignty.
The system is architected to function with zero reliance on external servers, ensuring that you can go completely offline if your use case demands it.

## Data Sovereignty

You own your data.
Your entire knowledge base—your private entries, your peer configurations, and all your reports—is stored locally on your own machine.
You can back it up, encrypt it, or delete it at any time.
At no point is your private data uploaded to a cloud service or third-party platform.

## Peer-to-peer Architecture

There are no central servers in Hinter Net.
All communication happens directly between the machines of you and your peers.
Furthermore, communication between peers is end-to-end encrypted.
Even if an attacker were to intercept the network traffic, it would be unintelligible to them.

## Local LLM-first Design

We actively prioritize locally hosted models over external API services to fully protect user sovereignty.
Consequently, we do not build official tools that favor specific commercial AI services like GitHub Copilot, Gemini CLI or Claude Code.
We also deliberately avoid designing core workflows that demand massive context windows or specialized agentic capabilities, which may create a soft vendor lock-in.
The ideal and strongly recommended path is to power your AI assistant with a local LLM.

:::info The Future is Local
We recognize that hosting capable LLMs locally is still an emerging capability.
However, it is safe to view this as a temporary bottleneck.
You do not need the state-of-the-art model; just an adequate one, which will be widely achievable with local setups soon enough.
:::

## Hinter Net vs. Alternatives

Hinter Net's unique combination of principles sets it apart from other platforms.

- **vs. Public Social Networks (Twitter, etc.)**: Hinter Net is private and high-signal by design.
  It's about depth of connection with a trusted few, not breadth of connection with a noisy crowd.
- **vs. Team Collaboration Tools (Slack, etc.)**: Hinter Net is decentralized and peer-to-peer.
  There is no central company or server that owns the platform or your data.
  Your network is your own.
- **vs. Personal Knowledge Management (Obsidian, etc.)**: While PKM tools are excellent for organizing personal notes, Hinter Net adds a crucial networking and AI-synthesis layer.
  It's not just about what you know; it's about what you and your network know together, and how an AI can help you make sense of it all.

Hinter Net is not intended to replace these platforms, but to complement them.
For instance, you can aggregate your own data from various siloed platforms to enrich your private knowledge base.
Your AI assistant can then leverage this unified context to compose responses to queries, regardless of which platform they originate from.

# Roadmap and Contribution (docs/hinter-net/roadmap.md)

The future of Hinter Net is defined by a commitment to a stable, secure, and minimal core that empowers its community.
Our roadmap is guided by a simple principle: the most valuable work happens on the network, not on the code.

## Core Principles of Development

### 1. Minimal and Stable Core

Our primary goal is to keep the codebase of our officially supported tools, hinter-core and hinter-cline, as minimal as possible.
We achieve this by offloading features wherever possible to well-maintained, open-source projects that can run completely offline.
This minimalism is a critical security feature: a smaller, stable codebase is easier for users to audit, understand, and ultimately trust with their most sensitive information.

### 2. Modularity

While hinter-cline is designed to be a complete and adequately user-friendly client, it is just one possible interface.
The hinter-core application is what defines the underlying protocol through its implementation.
We explicitly encourage and support the community to develop alternative clients on top of this core.

:::warning Always Verify
This freedom is powerful, but it comes with a responsibility.
When you use a client not officially supported by the core team, you are trusting that client with your data.
Always carefully review the source code and security practices of any tool before using it.
:::

### 3. Extended by the Community

Future functionality, such as mobile clients or agentic web scrapers, is expected to come from the community.
The core team will focus on maintaining a bare minimum set of tools, while users are empowered to build the specific tools they need to enhance their networking efforts.

## The Most Important Contribution: Using the Network

This leads to the most critical point in our philosophy: **The best way to contribute to Hinter Net is to use it.**

The project's ultimate goal is to help you forge an expansive and influential intelligence network.
This is the real work.
We urge you not to fall into the trap of endlessly wanting to write code for the system.
Instead, focus on using the system effectively.
Build your network, exchange reports, and create value.

Only when you encounter a genuine obstacle in your networking efforts should you consider building a new tool.
Contribution through code should be driven by real-world necessity, not by a desire to add features for their own sake.
The true measure of Hinter Net's success will be the influence and effectiveness of the networks built upon it.

# Get Involved (docs/hinter-net/get-involved.md)

The most valuable contribution is to use Hinter Net to connect with your peers and expand the network by onboarding new ones.

## Finding Your First Peers

A common question is: "I like what I hear but I don't know who to add. What do I do?"
Here are some suggestions:

- **Start with a Few People You Already Trust**: Think about colleagues, friends, or collaborators with whom you already share information.
  Introduce them to Hinter Net and see if they're interested in a more secure and efficient way to communicate.
- **Leverage Your Peers' Networks**: The next best thing to a person you trust is a person trusted by someone you trust.
  Ask your initial peers to introduce you to suitable contacts in their own networks and help you onboard them as new hinters.
  This is the primary way a high-trust network expands.
- **Use the Public Channels**: The public channels listed below, especially the Discord, are the designated places to find other new users.
  Introduce yourself, state your interests, and you will likely find others who are also looking to build their first connections.
- **Be Patient**: A high-trust network is not built overnight.
  Start small and focus on creating value within that small circle. As you all see the benefits, the network will grow organically.

:::tip Recruiting from Public Channels
When recruiting peers from public channels, people will only connect if they trust you and believe you can provide value.
You can establish this by leveraging an existing professional reputation (on platforms like X, LinkedIn, or GitHub) or by building a new one through active, insightful participation in public discussions.
Give potential peers a reason to believe connecting with you is a valuable addition to their network.
:::

---

## Contributing Through Code

As outlined in our **[Roadmap and Philosophy of Contribution](./roadmap.md)**, our goal is to keep the core tools minimal and stable.
We do not encourage contributions to the official hinter-core and hinter-cline repositories unless they are bug fixes.

Instead, contribution through code should be driven by real-world necessity as you build your network.
The protocol is open, and we explicitly encourage developers to:

- **Build Alternative Clients**: If hinter-cline doesn't suit your workflow, build a hinter-core-compatible alternative.
- **Create Companion Tooling**: See a need for a mobile client, a data visualization tool, or an automated scraper?
  Build it.
- **Fork and Modify**: If you disagree with the direction of the official tools, you are free to fork them and create your own versions.

This permissionless innovation is key to a resilient and decentralized network.
However, always remember the security implications of using third-party tools and review their code carefully.

## Public Channels

These channels are primarily for initial contact, announcements, and finding your first peers.

- **Discord**: The [Api3 Discord](https://discord.gg/api3dao) has channels dedicated to Hinter Net for public discussion.
- **X**: Follow [@hinter_net](https://x.com/hinter_net) for updates.

# hinter-core (docs/hinter-core/introduction.md)

**hinter-core** is the networking engine of [Hinter Net](../hinter-net/introduction.md).
It is the reference implementation of the **hinter protocol**, a secure, P2P system for exchanging intelligence reports between trusted peers.
hinter-core is built using the Hypercore stack (also used by [Pear Runtime](https://pears.com/)), which provides the underlying P2P and cryptography layers.

hinter-core runs as a quiet background service, managing your cryptographic identity and handling the secure exchange of reports.
It has no graphical interface of its own; its sole purpose is to be a robust and reliable data transport layer, allowing you to focus on crafting intelligence in its companion application, [hinter-cline](../hinter-cline/introduction.md).

:::tip Don't Read, Chat!

You can copy-paste [`llms-full.txt`](https://hinter.net/llms-full.txt) to your preferred AI.

:::

### Key Features

- **Identity Management**: Creates and stores your unique cryptographic keypair, which serves as your identity on the network.
- **Peer-to-peer Networking**: Connects directly and securely to your peers' machines using their public keys.
- **Report Synchronization**: Automatically sends and receives report files.
- **End-to-end Security**: All communication is direct, P2P, and end-to-end encrypted, with no central servers.

To learn how to manage its configuration and directory structure, see the **[User Guide](./user-guide/hinter-core-data.md)**.

# `hinter-core-data/` (docs/hinter-core/user-guide/hinter-core-data.md)

:::info Prerequisites
This guide assumes you have completed the [Quickstart guide](../../hinter-net/quickstart.mdx).
:::

While hinter-core runs as a headless background service, it is managed entirely through its file structure.
Understanding its directories and configuration files is key to managing your network and troubleshooting issues.
All of your data is stored in the `hinter-core-data/` directory.

## Directory Structure

The `hinter-core-data/` directory is the heart of your Hinter Net presence.
It is created when you run the initialization script, as described in the [Quickstart guide](../../hinter-net/quickstart.mdx).

```
hinter-core-data/
├── .env                        # Your private keypair
├── .storage/                   # Automatically generated cache storage directory
├── hinter.config.json          # Global configuration (optional)
└── peers/
    └── {PEER_ALIAS}/           # Directory for a specific peer
        ├── hinter.config.json  # Configuration for this peer
        ├── incoming/           # Reports received from this peer
        └── outgoing/           # Reports to be sent to this peer
```

- **`.env`**: This file contains your unique `PUBLIC_KEY` and `SECRET_KEY`. You should back this file up in a secure location.
  - Share the `PUBLIC_KEY` with others so they can add you as a peer.
  - **Never share your `SECRET_KEY`**.
    It is the private key that controls your identity.
- **`.storage/`**: This directory gets generated automatically by hinter-core and acts as a cache storage for network data.
  It needs to be deleted while [moving `hinter-core-data/`](./how-to.md#migrate-to-another-working-directory-or-machine).
- **`peers/`**: This directory contains a sub-directory for each peer you add.
- **`peers/{PEER_ALIAS}/incoming/`**: Contains reports received from this peer.
  This directory is managed by hinter-core and should be treated as read-only.
- **`peers/{PEER_ALIAS}/outgoing/`**: Place files in this directory to send them to this peer.
  hinter-core will automatically detect and synchronize them.
  This is intended to be done using the hinter-cline helper tool.

## `--data-dir` Argument

The quickstart guide had you run hinter-core with no arguments, which requires `hinter-core-data/` to be in your home directory.

To customize the path of this directory, you can run hinter-core with the `--data-dir` argument.
For example, if `hinter-core-data/` is in your current working directory, you can use the following command.

```sh
hinter-core --data-dir "$(pwd)/hinter-core-data"
```

Similarly, you can use the `--data-dir` argument while running hinter-core with pm2.
Note that the `--` indicates where pm2 arguments end and where hinter-core arguments begin.

```sh
pm2 start hinter-core --name my-hinter-core -- --data-dir "$(pwd)/hinter-core-data"
```

The `--data-dir` value must be an absolute path.
hinter-core will reject relative paths such as `./hinter-core-data`.
This is because hinter-core is expected to be run by pm2 at startup, where the relative path would not resolve correctly.

## `hinter.config.json` (docs/hinter-core/user-guide/hinter-config-json.md)

You can apply settings globally or on a per-peer basis.
Peer-specific settings always override global settings.
These are advanced settings and are not typically needed for normal operation.

### Global Configuration

Create a file at `hinter-core-data/hinter.config.json` to set global defaults for all peers.

- `disableIncomingReports` (boolean, optional, default: `false`): If `true`, your hinter-core instance will not listen for or accept any incoming reports from any peer.
- `peerSizeLimitMB` (number, optional, default: `1024`): The maximum size (in megabytes) a peer's `incoming/` directory can reach before they are automatically blacklisted to prevent abuse.

:::info Managing Blacklisting
When the `peerSizeLimitMB` is exceeded, the peer is blacklisted by creating an empty file named `.blacklisted` in their peer directory.
To undo the blacklisting, the conditions that caused the blacklisting must be reversed, and this file needs to be deleted manually.
:::

### Peer-specific Configuration

Each peer's configuration is stored at `hinter-core-data/peers/{PEER_ALIAS}/hinter.config.json`.
This file is created automatically when you add a peer with the hinter-cline helper tool.

It **must** contain the peer's `publicKey`.
You can also add any of the global configuration keys here to override the default settings for just that peer.

**Example:**

```json
{
  "publicKey": "a1b2c3d4e5f6...",
  "disableIncomingReports": true,
  "peerSizeLimitMB": 2048
}
```

## How-tos (docs/hinter-core/user-guide/how-to.md)

As a general rule, back up your entire `hinter-core-data/` directory before attempting any of the following.
Do not remove the backup until you confirm that the operation is successful.

### Undo Peer Blacklisting

hinter-core automatically blacklists peers that may disrupt its operation, for example, because the peer is running two hinter-core instances with the same keypair in parallel.
It does this by creating a `hinter-core-data/peers/{PEER_ALIAS}/.blacklisted` file, which contains a message that explains the reason.
You can undo the blacklist by simply deleting the `.blacklisted` file.
However, note that the peer will soon be blacklisted again if the underlying reason isn't resolved.

### Upgrade hinter-core to Latest Version

Stop and delete the pm2 process named `my-hinter-core` that you created while following the [Quickstart guide](../../hinter-net/quickstart.mdx).

```sh
pm2 stop my-hinter-core
pm2 delete my-hinter-core
```

Then, install the latest hinter-core version and configure pm2 using the commands provided by the current [Quickstart guide](../../hinter-net/quickstart.mdx).

You can check the logs to ensure the new version started correctly.

```sh
pm2 logs my-hinter-core
```

:::info Migrating Through Breaking Changes
Some releases introduce breaking changes that require the user to handle.
Always read the respective [Release Notes](https://github.com/hinter-net/hinter-core/releases) before upgrading.
:::

### Update Keypair

You may want to update your keypair if it is compromised, or as a regular security practice.
To do so, stop the pm2 process named `my-hinter-core` that you created while following the [Quickstart guide](../../hinter-net/quickstart.mdx).

```sh
pm2 stop my-hinter-core
```

Use the following command to initialize a new hinter-core directory named `delete-after-use/`.

```sh
hinter-core-initialize --data-dir "$(pwd)/delete-after-use"
```

Overwrite the `.env` file in your `hinter-core-data/` directory with the `.env` file in `delete-after-use/`, and then delete the `delete-after-use/` directory.

Restart the pm2 process for hinter-core.

```sh
pm2 start my-hinter-core
```

Finally, you must share your new public key with your peers for them to be able to update your peer configuration on their end.

### Migrate to Another Working Directory or Machine

Stop and remove the pm2 process named `my-hinter-core` that you created while following the [Quickstart guide](../../hinter-net/quickstart.mdx).

```sh
pm2 stop my-hinter-core
pm2 delete my-hinter-core
```

Copy over your `hinter-core-data/` directory to the new machine, except the `.storage/` directory in it.

Follow the [Quickstart guide](../../hinter-net/quickstart.mdx) to start hinter-core on the new machine, skipping the initialization step.

:::warning Avoid Parallel Instances With the Same Keypair
hinter-core is designed to be operated as a single instance.
Do not run multiple instances with the same keypair.
:::

# Design and Protocol (docs/hinter-core/design-and-protocol.md)

The design of hinter-core is guided by a commitment to simplicity, robustness, and developer agility.
This section covers the core design principles and the technical details of the protocol.

## Design Philosophy

### File System as Database

hinter-core treats the file system as its database.
Peer configurations, incoming reports, and outgoing reports are all stored as plain files and folders.
This choice is fundamental:

- **Simplicity**: It eliminates the need for a separate database server, reducing setup and maintenance overhead.
- **Transparency**: You can directly observe the state of the system by looking at the files. There is no hidden state.
- **Interoperability**: Any tool that can read a file system can interact with hinter-core's data, making it easy to script and extend.

### Protocol as Implementation

The hinter protocol is not defined by a standalone specification document.
Instead, the hinter-core codebase _is_ the specification.
This approach offers several advantages for a young and evolving project:

- **Agility**: The protocol can be updated and improved quickly without a lengthy standards process.
- **Accuracy**: The implementation is, by definition, always 100% compliant with the protocol.
- **Pragmatism**: It prioritizes a working system over abstract documentation, ensuring that development is grounded in practical reality.

:::info hinter-core Alternatives
This implies that users can maintain hinter-core alternatives as long as they are compatible with the canonical hinter-core implementation.
:::

### Focused Responsibility

hinter-core has a single, clear job: to handle the P2P exchange of files.
It does not concern itself with the content of those files, user interfaces, or advanced data processing.
This strict separation of concerns ensures that hinter-core can be optimized for reliability and security as the foundational transport layer of Hinter Net.

## Protocol Implementation

Under the hood, hinter-core uses a collection of modules for building peer-to-peer, append-only logs.

### How Synchronization Works

Synchronization in hinter-core is a process of mirroring a sender's `{RECIPIENT_ALIAS}/outgoing/` directory to a recipient's `{SENDER_ALIAS}/incoming` directory.
The sender's directory is treated as the definitive source of truth.

1.  **Append-only Log**: Each peer maintains an append-only log of its `outgoing/` directory.
    When a file is added, modified, or deleted, a new entry is appended to this log, creating a verifiable history of changes.
2.  **Peer Connection**: When two peers connect, they exchange information about their logs.
3.  **One-way Mirroring**: For each peer connection, the synchronization is one-way.
    The recipient peer downloads any changes it is missing from the sender's log.
    The recipient always defers to the sender's log; the sender's machine knows best what it wants to send.
4.  **File System Update**: As the recipient receives new log entries, it updates its `incoming/{SENDER_ALIAS}` directory to perfectly mirror the sender's `{RECIPIENT_ALIAS}/outgoing/` directory.

This append-only log structure provides a robust and efficient way to keep directories synchronized between peers in a decentralized manner, with a clear chain of authority for the data being exchanged.

# Security Practices (docs/hinter-core/security-practices.md)

The following is a list of security practices.
It is not expected that all users will adopt all of these.
You should pick and choose the ones that are appropriate for your specific use case and threat model.

### Keep Your Secret Key Secure

Never expose your `SECRET_KEY` in the `.env` file.

### Share Your Public Key on a Need-to-know Basis

Only share your public key with people you intend to communicate with to minimize potential attack surfaces.

### Self-host

Keep everything on your own local machine.
Do not move your `hinter-core-data/` directory to a remote machine, such as one that belongs to a commercial cloud provider.
Do not push your `hinter-core-data/` directory to remote repositories on platforms like GitHub.

### Secure Your Machine

Use a trusted OS and configure your firewall to minimize the attack surface.
Do not use any additional software that is able to spy on you (e.g. Windows Copilot/Recall).

### Vet Upgrades and Build Locally

Before upgrading hinter-core to a new version, review the code changes in the new version.
Pull the tagged commit and build the npm package locally on your own machine.

### Encrypt Your Data

Store your `hinter-core-data/` directory on an encrypted volume against physical attacks.

### Anonymize Your IP

Anonymize your IP address using a VPN or Tor for privacy.

### Use a Custom DHT Bootstrap Node

hinter-core uses the DHT bootstrap nodes provided by the Hypercore stack by default.
Run your own and configure hinter-core to use it.

### Randomize Activity Patterns

Randomize your activity patterns to hide your timezone and schedule.

# hinter-cline (docs/hinter-cline/introduction.md)

If [hinter-core](../hinter-core/introduction.md) is the engine of your network, **hinter-cline** is your command center.
hinter-cline provides you with a personal instance of VS Code that runs in your browser, accessible at `localhost:8080`.
This environment comes pre-packaged with [Cline](https://cline.bot), a sophisticated AI assistant, and is securely sandboxed within a Docker container.

:::tip Don't Read, Chat!

You can copy-paste [`llms-full.txt`](https://hinter.net/llms-full.txt) to your preferred AI.

:::

### What You Do in hinter-cline:

With the assistance of Cline, you can:

- **Process Intelligence**: Read and analyze incoming reports from your peers.
- **Maintain Your Knowledge Base**: Keep a private journal of entries, notes, and insights in the `entries/` directory.
- **Compose Reports**: Compose personalized and contextualized reports for your peers.
- **Manage Your Network**: Use the built-in helper command-line tool to easily add peers, create groups, and synchronize your outgoing reports.

To learn about its features, including the helper tool, see the **[User Guide](./user-guide.md)**.

# User Guide (docs/hinter-cline/user-guide.md)

:::info Prerequisites
This guide assumes you have completed the [Quickstart guide](../hinter-net/quickstart.mdx).
:::

The primary way you will manage your peers, groups, and reports is through the interactive command-line helper tool.

## Running the Tool

1.  Open the hinter-cline VS Code interface in your browser (`http://localhost:8080`).
2.  Open a new terminal (`Terminal` > `New Terminal`).
3.  In the terminal panel that appears, run the command `npm start`.
    This will launch the helper tool.

## Menu Options

- **Create a report draft**: This helps you create a new report draft file in your `entries/` directory.
  It will prompt you for a title and let you select recipients from a list of your known peers and any groups you have created.
  Note that you can move this file to anywhere in your `entries/` directory.
- **Sync reports**: This is a crucial command.
  It scans all draft files in your `entries/` directory and synchronizes them with your peers.
  It reads the YAML frontmatter in each draft and copies the specified content to the correct `outgoing/` directory for hinter-core to send.
  It also removes reports from the `outgoing/` directory if a peer is no longer a recipient.
- **Add/Manage a peer**: This menu lets you add a new peer by providing their alias and public key, or edit/delete an existing peer.
- **Add/Manage a group**: This menu lets you create peer groups (e.g., "work", "friends") to make sending reports to multiple people at once easier.
  You can create new groups, add peers to existing groups, or remove them.

## Report Draft Frontmatter

The core of the reporting system is the YAML frontmatter at the top of each report draft file.

- `to`: A list of recipients. Can contain individual peer aliases (e.g., `"peer-1"`) and groups (e.g., `"group:friends"`).
- `except`: A list of peers or groups to exclude from the `to` list.
- `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.

:::tip Sharing Beyond Text
The `sourcePath` property is powerful.
It allows you to share more than just text reports.
You can point it to a video file, a folder full of memes, or even a static website to share complex intelligence with your peers.
:::

### Example

```yaml

# A Private Report

Hi peer-alias-1 and my-friends, please do not share this with peer-alias-3.
```

When you run `Sync reports`, the content of this file will be sent to `peer-alias-1` and all members of the `my-friends` group, except for `peer-alias-3`.

### Using the Implicit `all` Group

You can refer to the implicit `all` group, which includes all your peers.

```yaml
---
to: ["group:all"]
except: []
sourcePath: ""
destinationPath: ""
---
# General Announcement

Hi everyone!
```

When you run `Sync reports`, the content of this file will be sent to all your peers.
You do not need to add or manage the `all` group.

## Git-based Workflow

The `hinter-cline` container automatically initializes your `hinter-core-data/` directory as a Git repository on its first run.
This means any new reports you receive or entries you create will appear as changes in `git diff`.

You are encouraged to commit these changes periodically to create checkpoints in your knowledge base's history.
You don't need to worry about crafting perfect, navigable commit histories; the primary utility is in being able to easily review changes since your last session.
You can review the diffs yourself in the VS Code interface or have your AI assistant do it for you.

## How to

### Upgrade hinter-cline to Latest Version

Stop and remove the container named `my-hinter-cline` that you created while following the [Quickstart guide](../hinter-net/quickstart.mdx).

```sh
docker stop my-hinter-cline
docker rm my-hinter-cline
```

Then, start hinter-cline using the command provided by the current [Quickstart guide](../hinter-net/quickstart.mdx), which will use the latest version.

:::info Migrating Through Breaking Changes
Some releases introduce breaking changes that require the user to handle.
Always read the respective [Release Notes](https://github.com/hinter-net/hinter-cline/releases) before upgrading.
:::

You can visit http://localhost:8080 to ensure the new version started correctly.

# Workflows and Tips (docs/hinter-cline/workflows.md)

hinter-cline is a flexible environment.
While you can develop your own methods, here are some recommended workflows and practical tips to get you started.

## The Core Workflow

The fundamental workflow for a hinter is a continuous cycle:

1.  **Ingest**: Review the `git diff` of the `incoming/` directories to see what has changed since your last session.
    You can then hyperlink to these reports from your `entries/` directory, or copy them over if you deem them critical.
    Once you have reviewed the new intelligence, commit the changes to mark them as seen.
2.  **Curate**: Collect intelligence from various sources and record it in your private `entries/` directory, adding your own thoughts and connections.
3.  **Compose**: Create new report drafts or maintain canonical ones that need to be updated at the other peers' end.
4.  **Distribute**: Use the `Sync reports` command in the helper tool to send your final report drafts to the designated recipients.

:::tip Use Your AI Assistant
Remember that you are in an AI-assisted environment. You do not have to perform these steps manually. For example, instead of reading the incoming report diffs yourself, you can ask the AI to do it for you and summarize anything that might be of interest. Similarly, you can ask the AI to synthesize new information, compose draft reports, and more.
:::

## The Reporting Workflow

Reports can be one-time dispatches, like a newsletter, or they can be canonical, living documents that you maintain and update over time for your peers.
The workflow is the same for both:

1.  **Create a Draft**: Use the helper tool to create a new report draft.
    This will prompt you for a title and recipients, and create the draft file with the correct frontmatter.
2.  **Compose**: Write your content in the newly created Markdown file.
3.  **Sync and Send**: Run the `Sync reports` command from the helper tool.
    This scans all your drafts and sends them to the correct peers.

This helper-driven workflow is the recommended way to manage your reports. You only need to manually edit the frontmatter for advanced use cases, such as changing the `sourcePath` or modifying the recipient list after the draft has been created.

## Practical Tips

### Your Daily AI Assistant

While hinter-cline is designed for hinter workflows, it's also a powerful, standalone AI assistant.
Because it has access to your entire knowledge base, you can ask it anything about the information you've curated.

For example, you can ask:

- "I've been on holiday for a week. Give me a catch-up report on what I've missed."
- "Are there any new people I should connect with, based on my current network and interests?"
- "Give me a profile on Alice based on all the information I have."

### Context Isolation

Use the "New Task" button in the Cline sidebar frequently.
Start a new task for each distinct piece of work (e.g., one task for your daily briefing, another for drafting a report to a specific group).
This keeps the AI's context focused and prevents information from unrelated conversations from influencing its output.

### Composing with the AI

Treat the AI as a collaborative partner.

- **Start broad, then refine**: Give the AI a high-level goal first ("Draft a report to the 'dev' group about the new Docker security vulnerability").
- **Iterate**: Review the AI's draft and provide specific feedback ("Make the tone more urgent," "Add a link to the official patch notes," "Can you simplify the technical explanation in the second paragraph?").
- **Use Act Mode for Edits**: Once you have a plan, switch to Act Mode and let the AI make the changes directly to the file.

### Linking Your Knowledge

You can create a powerful, interconnected knowledge base by linking your entries.
When you create a new entry that relates to an existing one, you can add a Markdown link to it.
For example, if you have an entry about a company called "Acme Corp" and you create a new entry about its CEO, you can link the two like this:

`[Acme Corp](../entries/acme_corp.md)`

This creates a relationship between the two entries that your AI assistant can understand and use to provide more contextually aware responses.

# Security Practices (docs/hinter-cline/security-practices.md)

Many of the foundational security and privacy recommendations for the Hinter Net ecosystem are covered in the [hinter-core Security Practices](../hinter-core/security-practices.md).
It is strongly recommended to review those first.
This page covers additional best practices specific to `hinter-cline`.

## Use a Local LLM to Power Your AI Assistant

To maintain full data sovereignty, the ideal and strongly recommended path is to power your AI assistant with a local LLM.

## Only Add Trusted Peers

A high-trust network requires careful vetting of its members.
Information received from a non-trusted peer is not actionable, and you cannot disclose sensitive information to them in return.
Furthermore, adding any peer creates a potential, if small, attack surface.
For these reasons, you should only add peers you trust.

## Vet Real-world Identities

To protect yourself against impersonation of real or fabricated identities by humans or bots, it is crucial to vet the real-world identity of anyone you add as a peer.

:::note Key Hinter Identity Recovery
Vetting real-world identities also provides a path for a peer to be reintegrated into the network if their cryptographic key is ever compromised.
:::

## Back Up Your Data

Your `hinter-core-data/` directory is the heart of your Hinter Net presence.
It contains your cryptographic identity, your entire knowledge base, and all your peer configurations.
It is critical to back up this directory regularly to a secure, private location.

## Be Wary of Malicious Content

You can receive malicious content even from trusted peers.
Always exercise caution when running code or executables received through the network.