Add summary architecture and contributing guides

.gitignore

@@ -1 +1,2 @@
 /public/
+*.bak

content/docs/architecture.smd

@@ -0,0 +1,88 @@
+---
+.title = "Architecture",
+.date = @date("2025-07-06T00:00:00"),
+.author = "CJ van den Berg",
+.layout = "index.shtml",
+.draft = false,
+---
+
+This document describes in a general way, concepts that help to
+understand how the code is organized and where to look at when starting
+to contribute developing Flow Control.  Make sure you have read
+first [help.md](https://github.com/neurocyte/flow/blob/master/help.md)
+and use the editor at least in flow mode. We recommend reading the
+[deepwiki description](https://deepwiki.com/neurocyte/flow) and join
+[Discord](https://discord.com/invite/4wvteUPphx) to ask from the
+simplest.
+
+## Internals
+
+The foundational unit is the `Buffer` that holds the document in memory;
+there might be various opened files, each one loaded in a buffer.
+A buffer can be ephemeral, meaning, it is not related to a file, that
+might be the product of a `Task` run.  Buffers are implementations of
+ropes that offer multiple services such as insert characters, load from
+file, write to file, load from string, return as string, tell if it has
+unsaved changes(dirty), among many others. A buffer can have multiple
+`Selections` and `Cursors` interacting with it. The `Buffer Manager`
+offers services around the set of buffers.
+
+A `Project` initially is the directory where flow is opened at, once
+opened, it starts processes to discover the files under the directory
+hierarchy, interact with lsp and git. When flow is opened, only one
+active project is loaded in the current session. The `Project Manager`
+offers services around the set of projects.
+
+## Editor commands and modes
+
+When a buffer is active, it has an `Editor` attached to it; an editor
+might have associated tree-sitter support, given the file type detected,
+and offers common services that are aimed to be used by `Commands` to
+manipulate the contents of a buffer at a higher level, the selections,
+cursors and the `View`. The commands are used by `Modes` with
+`Keybindings`. The main mode is Flow and the keybindings can be used
+to map to a mode built up entirely on solely calling already created
+commands. An example of a mode created by command composition is
+`Emacs` mode, for instance, it's possible to create a nano mode with
+just keybindings. In the other hand, `Vim` and `Helix` modes have
+particular definitions for commands that interact with the buffers,
+being modal editors.
+
+## Text user interface
+
+`Tui` governs it all offering support for `Palettes` that are known
+in other environments as pickers, as well as offering information
+through a set of `_views` (i.e. `logview`, `inputview`,
+`inspector_view`) and `status` (i.e. `tabs`, `clock`, `branch`,
+`linenum`).
+
+## Operating systems and UI
+
+libvaxis is in charge of rendering the text and all the interface in
+Linux, MacOS, FreeBSD, while in Windows there is an special GUI.
+
+## Communication between components
+
+[Thespian](https://github.com/neurocyte/thespian) is in charge of
+sending messages between different flow components, for example,
+when a widget needs updating information from changing states of
+internal data and when components or external processes take
+time, for example, tree-sitter queries to highlight the current
+file, of a particular language, LSPs, git, running a `shell`
+command via a `task`.
+
+## Programming languages
+
+There are plenty of programming languages that use tree-sitter via
+[flow-syntax](https://github.com/neurocyte/flow-syntax) and whose
+language servers and formatters are configured via `file_type_lsp`.
+Currently one Language Server is supported for each language.
+
+## Facilities
+
+Logging support offers various levels to give feedback for various
+actions that ease developing Flow itself and also are used to offer
+feedback via `logview`.
+
+
+You can find [contributing guidelines](/docs/contributing).

content/docs/contributing.smd

@@ -0,0 +1,79 @@
+---
+.title = "Contributing",
+.date = @date("2025-07-06T00:00:00"),
+.author = "CJ van den Berg",
+.layout = "index.shtml",
+.draft = false,
+---
+
+
+## Asking for a feature
+
+Please [open an issue](https://github.com/neurocyte/flow/issues) that
+explains what is the requirement, being as descriptive as
+possible.  First review other issues in case someone already
+requested the feature, or join
+[Discord](https://discord.com/invite/4wvteUPphx) to ask for
+more information.  At the end, the issues in github have more
+chance to get developed, given that there are plenty of things
+to do for this kind of software.
+
+## Reporting a problem
+
+If you discover a problem, or unexpected behaviour, feel free to
+join [Discord](https://discord.com/invite/4wvteUPphx) to check
+if there is a simple way to overcome the inconvenience or to get
+some guidance.  [Reporting a bug](https://github.com/neurocyte/flow/issues)
+is a good way to contribute. When reporting one, it should contain:
+
+* Flow version. You get it with `flow --version`
+* What you were doing, if possible step, by step to reproduce it
+* What actually happened
+* What was expecting to happen
+* Any other information, like screenshots, video, screencast, the
+platform allows to add that information.
+
+Issues later on are tagged with proposed version to solve it, in case it's a
+low hanging fruit, it's possible that it can be solved pretty quick.
+
+Spreading the word is another way to contribute to Flow Code growth.
+
+## Developing
+
+[Flow Control](https://flow-control.dev/) is programmed with
+[zig](https://ziglang.org/).
+
+[Fork](https://github.com/neurocyte/flow/fork), no worries, if you
+happen to use [codeberg](https://codeberg.org/neurocyte/flow), or
+[sourcehot](https://git.sr.ht/~neurocyte/flow), it's possible to
+fork and contribute via those services too.
+
+Discussing via [Discord](https://discord.com/invite/4wvteUPphx) is a good
+start to talk about what you are about to offer, or if you decide to pick
+an open issue, is a good practice first opening an issue and
+commenting in one of the channels to get some feedback and get to
+agreements or find guidance.
+
+This [summary](/docs/architecture) can help on getting started to
+follow the codebase.
+
+### Coding style
+
+Please follow what you see in the source code for functions, Structs,
+variables, const names, etc...  Functions have descriptive names to
+use less time adding and maintaining comments to communicate the
+purpose and intent.
+
+### Testing
+
+It's possible that the test set grows as the project evolves, given
+that the amount of relationships among components increase the
+opportunity to generate regressions.
+
+## Getting in touch.
+
+
+[Discord](https://discord.com/invite/4wvteUPphx) and
+[Github issues](https://github.com/neurocyte/flow/issues) are the
+main channels to do so.
+

content/docs/index.smd

@@ -4,24 +4,7 @@
 .author = "CJ van den Berg",
 .layout = "index.shtml",
 .draft = false,
---- 
+---
 
-The terminal Editor that came to reallity
-
-## Features
-We have keybindings
-
-We have modes
-
-We have syntax highlighting
-
-We have multiple cursors
-
-## Differential
-
-## What we have
-
-## Friendly Projects
-* [Zig](https://ziglang.org/)
-* [Zine](https://zine-ssg.io/)
-* [Monospace Web](https://owickstrom.github.io/the-monospace-web/)
+* [Architecture overview](/docs/architecture)
+* [Contributing](/docs/contributing)