Skip to content

Commit 2b28745

Browse files
AksemAksem
committed
Rework docs index page
1 parent e2941f2 commit 2b28745

2 files changed

Lines changed: 83 additions & 123 deletions

File tree

‎docs/getting-started.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,12 @@ uvx finecode bootstrap
3939
This creates `.venvs/dev_workspace/` with FineCode installed, using the exact
4040
versions specified in your `pyproject.toml`.
4141

42+
Activate it before running subsequent `python -m finecode` or `python -m pip` commands:
43+
44+
```bash
45+
source .venvs/dev_workspace/bin/activate # Windows: .venvs\dev_workspace\Scripts\activate
46+
```
47+
4248
**Manual alternative** (if you prefer not to use pipx/uvx — requires pip 25.1+):
4349

4450
```bash

‎docs/index.md‎

Lines changed: 77 additions & 123 deletions
Original file line numberDiff line numberDiff line change
@@ -1,172 +1,126 @@
11
# FineCode
22

3-
**FineCode gives you one workflow for code quality and developer tooling across CLI, IDE, CI, and AI assistants.**
3+
**FineCode gives you one intent-based workflow for developer tooling across CLI, IDE, CI, and AI assistants.**
44

5-
FineCode organizes your tooling so tasks like linting, formatting, type checking, build, and publish follow one consistent workflow and can be reused across projects.
5+
Most teams end up wiring the same tooling logic multiple times: shell scripts for local use, YAML for CI, editor integration, and now MCP or AI-specific glue. FineCode gives you one reusable layer instead, so `lint`, `format`, `type-check`, environment preparation, and other workflows follow the same model everywhere. In FineCode, those intents are modeled as reusable actions.
66

7-
Start in one repository in minutes. Then package the same setup and reuse it across your other projects.
7+
For example, you can define `lint` once and then reuse that same intent:
88

9-
## Start in minutes
9+
- in the terminal: `python -m finecode run lint`
10+
- in CI: run `lint` as part of your pipeline
11+
- in the IDE: surface `lint` through the editor integration
12+
- in AI workflows: expose `lint` through MCP
1013

11-
Add FineCode and a preset to your `pyproject.toml`:
14+
Start in one repository. Reuse the same standards across many. Keep the setup flexible instead of locking your project to one tool or one interface.
1215

13-
```toml
14-
[dependency-groups]
15-
dev_workspace = ["finecode==0.3.*", "fine_python_recommended==0.3.*"]
16+
## Why teams use FineCode
1617

17-
[tool.finecode]
18-
presets = [{ source = "fine_python_recommended" }]
19-
```
18+
### One workflow across local runs, CI, IDE, and AI
2019

21-
Run FineCode:
20+
FineCode lets you define actions once and run them through the surfaces developers already use:
2221

23-
```bash
24-
# initial one-time setup
25-
python -m venv .venvs/dev_workspace
26-
source .venvs/dev_workspace/bin/activate # Windows: .venvs\dev_workspace\Scripts\activate
27-
python -m pip install --group="dev_workspace"
28-
python -m finecode prepare-envs
22+
- Local CLI: `python -m finecode run lint`
23+
- CI: run the same actions instead of re-creating tool wiring in pipelines
24+
- IDE: connect through the [VSCode and MCP setup guide](getting-started-ide-mcp.md)
25+
- AI assistants: expose the same action surface through MCP-compatible clients
2926

30-
# now you are ready to use finecode
31-
# e.g. lint the whole workspace:
32-
python -m finecode run lint
33-
```
27+
That means less duplicated glue code and fewer mismatches between "what works on my machine" and "what CI expects".
3428

35-
NOTE: `pip install --group` requires pip 25.1+.
29+
### Explicit action model, not ad-hoc scripts
3630

37-
This gives you a working Python baseline with Ruff, Flake8, and isort through one shared config entry point.
31+
FineCode is built around explicit actions and handlers: define the operation once, then plug in the tooling that implements it.
3832

39-
## From one project to reusable standard
33+
That makes it easier to:
4034

41-
Once this works in one project, turn it into a shared preset and use it across repositories:
35+
- swap tools without redesigning the whole workflow
36+
- keep a stable command surface as your stack evolves
37+
- support mixed-language workspaces with a clearer abstraction boundary
38+
- reason about what your tooling setup actually does
4239

43-
```toml
44-
[dependency-groups]
45-
dev_workspace = ["finecode==0.3.*", "my_team_standards==0.1.*"]
40+
If you want the deeper reasoning, the docs now explain it directly:
4641

47-
[tool.finecode]
48-
presets = [{ source = "my_team_standards" }]
49-
```
50-
51-
```bash
52-
python -m pip install --group="dev_workspace"
53-
python -m finecode prepare-envs
54-
```
42+
- [Why FineCode's Action Model Works](theory/why-action-model.md)
43+
- [Designing Actions](guides/designing-actions.md)
5544

56-
Projects can then adopt updates through normal dependency updates.
57-
See [Creating a Preset](guides/creating-preset.md) for the packaging flow.
58-
59-
You can also combine presets in one project (for example, a language preset and a team preset):
45+
### Reusable standards for teams
6046

61-
```toml
62-
[tool.finecode]
63-
presets = [
64-
{ source = "fine_python_recommended" },
65-
{ source = "my_team_standards" },
66-
]
67-
```
47+
FineCode presets let you package your tooling setup once and share it across repositories. Start with a built-in preset, then turn your own conventions into a reusable standard for your team.
6848

69-
Typical rollout:
49+
- adopt a working baseline quickly
50+
- refine it in a real project
51+
- publish it as a shared preset
52+
- roll out updates through normal dependency updates
7053

71-
1. Start with a preset in one repository.
72-
2. Tune handlers and action config to fit your workflow.
73-
3. Publish that setup as a preset package for your team.
74-
4. Reuse it across repositories.
54+
See [Creating a Preset](guides/creating-preset.md) for the packaging flow.
7555

76-
## Why developers use FineCode
56+
### Isolation without fragmentation
7757

78-
### Core benefits for every project
58+
FineCode keeps developer tooling isolated from runtime dependencies while still presenting one coherent workflow to the team. You get more predictable execution without forcing every tool into a bespoke setup.
7959

80-
- Keep tooling config in one place instead of per-tool config sprawl
81-
- Use the same actions in terminal, IDE, and AI-assisted workflows
82-
- Spend less time wiring tools together and more time shipping code
83-
- Keep local runs and CI behavior aligned around the same actions
60+
### Built to grow from one repo to a workspace
8461

85-
#### One command surface for local, CI, IDE, and AI
62+
You can start small, but the model is designed for larger codebases too:
8663

87-
Use the same actions and config everywhere:
64+
- single-project repositories
65+
- multi-project workspaces
66+
- mixed-language setups
67+
- team-maintained tooling standards
8868

89-
- IDE: [VSCode extension setup](getting-started-ide-mcp.md#vscode-setup)
90-
- AI assistants: [MCP setup for AI clients](getting-started-ide-mcp.md#mcp-setup-for-ai-clients)
91-
- Local CLI: `python -m finecode run lint check_formatting`
92-
- CI: `python -m finecode run lint check_formatting`
93-
- Git hooks: run FineCode actions before commit without requiring `pre-commit`
69+
## Try it in minutes
9470

95-
#### Isolated environments by purpose
71+
Add FineCode and a preset to your `pyproject.toml`:
9672

97-
FineCode keeps developer tooling separate from runtime dependencies:
73+
```toml
74+
[dependency-groups]
75+
dev_workspace = ["finecode==0.3.*", "fine_python_recommended==0.3.*"]
9876

99-
```text
100-
.venvs/
101-
dev_workspace/ <- FineCode and presets
102-
dev_no_runtime/ <- lint/format/type-check handlers
103-
dev/ <- tooling that imports project code during execution
104-
runtime/ <- project runtime dependencies
77+
[tool.finecode]
78+
presets = [{ source = "fine_python_recommended" }]
10579
```
10680

107-
This reduces dependency cross-talk and makes tool execution more predictable.
108-
109-
These environment roles are examples, not fixed requirements. You can shape the layout to match your workflow.
110-
111-
#### Workspace-aware by design
112-
113-
FineCode understands your workspace as a whole, including how individual subprojects fit together.
114-
115-
Actions can target a single project or the entire workspace, so tasks like linting every subproject run from one command.
116-
117-
#### Polyglot workflow, one action surface
118-
119-
FineCode actions are not tied to a single language. A single action can include handlers for different file types (for example Python code, Markdown docs, and JSON/TOML config) while keeping one shared command surface.
81+
Bootstrap the workspace tooling environment:
12082

121-
In practice, this means you can keep using the same `lint` and `format` actions across mixed repositories today. Broader first-class preset coverage for combinations such as Python + Rust is on the roadmap.
122-
123-
### Additional benefits for teams
124-
125-
- Keep standards centralized in a shared preset package
126-
- Roll out toolchain changes through normal dependency updates
127-
- Keep rollout predictable by updating a shared preset package instead of editing each repository separately
128-
129-
## Flexible, no lock-in
130-
131-
Presets are a starting point, not a ceiling.
83+
```bash
84+
pipx run finecode bootstrap
85+
# or
86+
uvx finecode bootstrap
87+
```
13288

133-
Disable or tune individual handlers:
89+
Then activate the bootstrapped environment:
13490

135-
```toml
136-
[[tool.finecode.action_handler]]
137-
source = "fine_python_ruff.RuffLintFilesHandler"
138-
config.line_length = 120
139-
140-
[tool.finecode.action.lint]
141-
handlers = [
142-
{ name = "flake8", enabled = false },
143-
{ name = "my_linter", source = "my_team.MyLinterHandler" },
144-
]
91+
```bash
92+
source .venvs/dev_workspace/bin/activate
93+
# Windows: .venvs\dev_workspace\Scripts\activate
14594
```
14695

147-
Replace an action handler set completely:
96+
Then prepare tool environments and run your first action:
14897

149-
```toml
150-
[tool.finecode.action.lint]
151-
handlers_mode = "replace"
152-
handlers = [
153-
{ name = "my_linter", source = "my_team.MyLinterHandler" },
154-
]
98+
```bash
99+
python -m finecode prepare-envs
100+
python -m finecode run lint
155101
```
156102

157-
You can also add custom actions and handlers for project-specific workflows.
103+
This gives you a ready-to-use baseline for Python quality tooling through one shared entry point.
158104

159-
## Proven in this repository
105+
For the full setup flow, see [Getting Started](getting-started.md).
160106

161-
FineCode is used to run quality actions in the FineCode repository itself.
107+
## Why FineCode feels different
162108

163-
- TODO: Add repository-scale metrics (actions/day, CI duration impact, setup time before/after)
109+
FineCode is not just a wrapper around linters and formatters. It gives those tools a shared execution model, so the workflow stays coherent as your project grows.
164110

165-
## Ready to try FineCode?
111+
- Your team sees the same actions in terminal, CI, IDE, and AI-assisted flows
112+
- Your configuration has a clearer structure than a pile of unrelated tool configs
113+
- Your standards can move from "this repo's setup" to "our team's reusable preset"
114+
- Your docs can explain the model, not just list commands
166115

167-
[Get started in 5 minutes ->](getting-started.md)
116+
## Where to go next
168117

169-
See also: [Concepts](concepts.md), [Configuration](configuration.md), [available presets and extensions](reference/extensions.md)
118+
- [Getting Started](getting-started.md) for the full setup path
119+
- [IDE and MCP Setup](getting-started-ide-mcp.md) to connect editors and AI clients
120+
- [Concepts](concepts.md) for the core mental model
121+
- [Why FineCode's Action Model Works](theory/why-action-model.md) for the design rationale
122+
- [Designing Actions](guides/designing-actions.md) for action design guidance
123+
- [Extensions](reference/extensions.md) for available integrations
170124

171125
## Community
172126

0 commit comments

Comments
 (0)