> For the complete documentation index, see [llms.txt](https://novusedge0.gitbook.io/docket-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://novusedge0.gitbook.io/docket-docs/getting-started/quickstart.md).

# Your first decision

Create a project ledger, record a choice, and read it back. If Docket is not installed yet, follow [Installation](/docket-docs/getting-started/installation.md) first.

The commands below use a terminal. You can also ask your agent to carry out the same steps. With a plugin-only installation, use the agent's bundled Docket command or run the installer to make `docket` available in your shell.

## 1. Open your project

In your terminal, go to the project where you want to keep decisions. Replace this example path with your own:

```sh
cd ~/Projects/my-app
docket init
```

Docket creates `.docket/ledger.jsonl` in your repository. If you already have a private ledger for this project, it copies those records into the new file.

Run this to confirm which ledger is active:

```sh
docket where
```

The output should name the `.docket/ledger.jsonl` file in your project. To share it with your team, include `.docket/` in a Git commit.

## 2. Record a choice

For this example, imagine you are adding billing to an existing service:

```sh
docket decision "Which database should billing use?" \
  --choice "Postgres" \
  --rationale "We already run Postgres for the rest of the service" \
  --scope "billing/**"
```

In an empty ledger, Docket replies:

```
d1  adopted  Which database should billing use?
```

`d1` is the record's ID. Your ID may be different if the ledger already has records. `adopted` means this is a choice you have committed to.

The scope `billing/**` connects the decision to files under `billing/`. It helps Docket find the decision when you or your agent work on that part of the project.

## 3. Leave a question for later

```sh
docket question "Which database driver should billing use?" \
  --scope "billing/**"
```

In the same fresh ledger, this creates `q2`. The question stays open until you link a suitable answer to it.

## 4. Read your records

```sh
docket list
```

You will see the adopted decision and the open question. To read the decision in full, use the ID printed when you recorded it:

```sh
docket show d1
```

You can also open `docket graph` to browse the ledger in the terminal viewer.

## 5. Bring the choice into your next task

```sh
docket context --query "billing" --file billing/db.py
```

This prints a briefing for the task. With these two records, it includes your database choice and the question you still need to answer.

If you configured an agent during installation, start a new session in this project. Ask it to read the Docket context and tell you what is still open.

Continue with [Recording decisions](/docket-docs/everyday-use/recording.md) to learn how to answer the question or replace an earlier choice. [Working with your agent](/docket-docs/everyday-use/agents.md) shows how to use the same workflow in a conversation.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://novusedge0.gitbook.io/docket-docs/getting-started/quickstart.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.