Properly document audit + Minor improvements elsewhere

Author: ZakaHaceCosas

docs/about/roadmap.md

@@ -8,11 +8,7 @@ We'll expand (and rarely, but not impossibly, shrink) this roadmap as we make pr
 
 ## Upcoming release
 
-- [X] Rewrite the `audit` feature.
-    - [X] Fix known issues.
-    - [x] Support it everywhere NodeJS
-        - [x] pnpm
-        - [x] yarn
+No plans made as of now. We'll be thinking about what could we do for a 3.4 release, or a [4.0 release using these plans](#4x-plans).
 
 ---
 
@@ -80,7 +76,11 @@ We'll expand (and rarely, but not impossibly, shrink) this roadmap as we make pr
 
 ### Version 3.3
 
-[Upcoming.](#upcoming-release)
+- [X] Rewrite the `audit` feature.
+    - [X] Fix known issues.
+    - [x] Support it everywhere NodeJS
+        - [x] pnpm
+        - [x] yarn
 
 ---
 

docs/manual/audit.md

@@ -4,4 +4,36 @@
 
 The `audit` command is a command that automatically runs a security audit for a project you specify (or for all projects if no name is specified), and interrogates security vulnerabilities (if any) to determine if they're worth fixing.
 
-This is better explained [here](../learn/audit.md).
+## Usage
+
+Run the command alone to audit all added projects one by one, or specify a project root path / name to audit that project individually.
+
+```bash
+fkn audit [project-name]
+```
+
+What we'll do is run your package manager's `audit` command, and if any vulnerability exists, we'll analyze it to prompt you with some generic questions - e.g. "does this project use _x_ feature?".
+
+The whole purpose of this command is to find out if vulnerable dependencies are worth fixing or not, as sometimes a breaking-changes update might not be necessary. For example, if a certain package has a vulnerability related to cookies and your project is a simple RNative app that does not use cookies, it's considered _not worth fixing_.
+
+### The audit process
+
+A sample audit would look like this:
+
+```txt
+===     FOUND VULNERABILITIES (001)     ===
+
+GHSA-XXXX-XXXX-XXXX
+
+=== STARTING F*CKINGNODE SECURITY AUDIT ===
+
+Does your app use {x} feature? [V:XXX] [y/N]
+```
+
+The question prompted will vary on the identified "vulnerability vector" (denoted by the `[V:XXX]` code). Depending on your responses, we'll show different questions. Then we'll compute a percentage and show it to you, where 0% means _not worth fixing_ and 100% means _absolutely needs fixing_. This percentage, which we call Risk Factor, is computed using a basic scoring system and a bit of math.
+
+We made a research paper-like page [here](../learn/audit.md) explaining in detail how this works.
+
+---
+
+You've now learnt everything about F\*ckingNode.

docs/manual/index.md

@@ -10,13 +10,14 @@ These are links to individual pages. For the full manual, click the first one, t
 - [Configuration](configuration.md)
 - [Main usage guide](usage.md)
 - [Individual project config (fknode.yaml)](fknode-yaml.md)
-- [Extra - Kickstart](kickstart.md)
-- [Extra - Commit](commit.md)
-- [Extra - Release](release.md)
-- [Extra - Launch](launch.md)
-- [Extra - Surrender](surrender.md)
-- [Extra - Setup](setup.md)
-- [Extra - Stats](stats.md)
+- [Feature - Kickstart](kickstart.md)
+- [Feature - Commit](commit.md)
+- [Feature - Release](release.md)
+- [Feature - Launch](launch.md)
+- [Feature - Setup](setup.md)
+- [Feature - Stats](stats.md)
+- [Feature - Surrender](surrender.md)
+- [Feature - Audit](audit.md)
 - [What's next?](whats-next.md)
 
 For further learning:

docs/manual/surrender.md

@@ -72,4 +72,6 @@ This feature might seem a joke, but in reality, regardless of it being a project
 
 ---
 
-You've now learnt everything about F\*ckingNode.
+You've now learn how to ensure your JavaScript project dies properly.
+
+Next: Audit - how to make NodeJS security audits actually understandable.

docs/manual/usage.md

@@ -121,7 +121,7 @@ Available flags are:
 | `--commit`    |    does the obvious (commits) |
 | `--update`    |    does the obvious (updates) |
 
-\* if not obvious enough, removes files and directories you specify, such as `.react`, `out/`, `dist/`, or anything you'd like to do away with.
+\* if not obvious enough, removes files and directories you specify, such as `.react`, `out/`, `dist/`, or anything you want gone.
 
 !!! abstract "Cross-runtime support notice"
 

mkdocs.yml

@@ -20,14 +20,14 @@ nav:
           - Configuration: "manual/configuration.md"
           - Main usage guide: "manual/usage.md"
           - Individual project configuration: "manual/fknode-yaml.md"
-          - Extra - Kickstart: "manual/kickstart.md"
-          - Extra - Commit: "manual/commit.md"
-          - Extra - Release: "manual/release.md"
-          - Extra - Launch: "manual/launch.md"
-          - Extra - Setup: "manual/setup.md"
-          - Extra - Stats: "manual/stats.md"
-          - Extra - Surrender: "manual/surrender.md"
-          - Extra - Audit: "manual/audit.md"
+          - Feature - Kickstart: "manual/kickstart.md"
+          - Feature - Commit: "manual/commit.md"
+          - Feature - Release: "manual/release.md"
+          - Feature - Launch: "manual/launch.md"
+          - Feature - Setup: "manual/setup.md"
+          - Feature - Stats: "manual/stats.md"
+          - Feature - Surrender: "manual/surrender.md"
+          - Feature - Audit: "manual/audit.md"
           - Learn - Cross-runtime support: "learn/cross-runtime-support.md"
           - "What's next?": "manual/whats-next.md"