From 09dec1320f451eaf4ed2df78ad330cfa6dd26bdc Mon Sep 17 00:00:00 2001
From: Kevin Franklin Kim <kevin.kim@bestbytes.com>
Date: Fri, 19 Sep 2025 11:38:10 +0200
Subject: [PATCH] docs: update README

---
 Makefile  |  19 ++++++++--
 README.md | 111 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 124 insertions(+), 6 deletions(-)

diff --git a/Makefile b/Makefile
index 397b7a9..e667c3d 100644
--- a/Makefile
+++ b/Makefile
@@ -32,8 +32,8 @@ endif
 ### Tasks
 
 .PHONY: check
-## Run tests and linters
-check: tidy lint test
+## Run lint & test
+check: tidy lint test test.demo
 
 .PHONY: tidy
 ## Run go mod tidy
@@ -46,7 +46,7 @@ lint:
 	@golangci-lint run
 
 .PHONY: lint.fix
-## Fix lint violations
+## Run linter and fix
 lint.fix:
 	@golangci-lint run --fix
 
@@ -68,6 +68,18 @@ test.demo: install
 		make shell.build && \
 		bin/posh execute welcome demo
 
+.PHONY: build
+## Build binary
+build:
+	@rm -f bin/posh
+	@go build -o bin/posh main.go
+
+.PHONY: build.debug
+## Build binary in debug mode
+build.debug:
+	@rm -f bin/posh
+	@go build -gcflags "all=-N -l" -o bin/posh main.go
+
 .PHONY: install
 ## Run go install
 install: GOPATH=${shell go env GOPATH}
@@ -100,4 +112,3 @@ help:
 			print "\n                        " help "\n"; help=""; \
 		} \
 	}' $(MAKEFILE_LIST)
-
diff --git a/README.md b/README.md
index 99f7e3c..a8a016d 100644
--- a/README.md
+++ b/README.md
@@ -62,16 +62,123 @@ Use "posh [command] --help" for more information about a command.
 
 To start using posh, go into your project and run:
 
-```bash
+```shell
 $ cd your/project
 $ posh init
 ```
 
 This will generate the standard layout for posh which can be changed as required through `.posh.yml`.
 
+```yaml
+version: v1.0
+
+## Prompt settings
+prompt:
+  title: "Posh"
+  prefix: "posh >"
+  history:
+    limit: 100
+    filename: .posh/.history
+    lockFilename: .posh/.history.lock
+
+## Environment variables
+env:
+  - name: PATH
+    value: "${PROJECT_ROOT}/bin:${PATH}"
+
+## Ownbrew settings
+ownbrew:
+  binDir: "bin"
+  tapDir: ".posh/scripts/ownbrew"
+  tempDir: ".posh/tmp"
+  cellarDir: ".posh/bin"
+  packages: []
+    ## Remote package
+    ## See `https://github.com/foomo/ownbrew-tap`
+    #- name: gotsrpc
+    #  tap: foomo/tap/foomo/gotsrpc
+    #  version: 2.6.2
+    ## Local package `.posh/scripts/ownbrew`
+    #- name: example
+    #  version: 0.0.0
+
+## Requirement settings
+require:
+  ## Required environment variables
+  envs: []
+    ## Example: require VOLTA_HOME
+    #- name: VOLTA_HOME
+    #  help: |
+    #    Missing required $VOLTA_HOME env var.
+    #
+    #    Please initialize volta and ensure $VOLTA_HOME is set:
+    #
+    #      $ volta setup
+
+  ## Required scripts that need to succeed
+  scripts: []
+    ## Example: git
+    #- name: git
+    #  command: |
+    #    git status && exit 0 || exit 1
+    #  help: |
+    #    This is not a git repo. Please clone the repository
+
+    ## Example: npm
+    #- name: npm
+    #  command: npm whoami --registry=https://npm.pkg.github.com > /dev/null 2>&1
+    #  help: |
+    #    You're not yet logged into the github npm registry!
+    #
+    #      $ npm login --scope=@<SCOPE> --registry=https://npm.pkg.github.com
+    #      Username: [GITHUB_USERNAME]
+    #      Password: [GITHUB_TOKEN]
+    #      Email: [EMAIL]
+
+  ## Required packages to be installed on the host
+  packages: []
+    ## Example: git
+    #- name: git
+    #  version: '~2'
+    #  command: git version | awk '{print $3}'
+    #  help: |
+    #    Please ensure you have 'git' installed in the required version: %s!
+    #
+    #      $ brew update
+    #      $ brew install git
+
+    ## Example: go
+    #- name: go
+    #  version: '>=1.23'
+    #  command: go env GOVERSION | cut -c3-
+    #  help: |
+    #    Please ensure you have 'go' installed in the required version: %s!
+    #
+    #      $ brew update
+    #      $ brew install go
+
+    #- name: volta
+    #  version: '>=2'
+    #  command: volta --version
+    #  help: |
+    #    Please ensure you have 'volta' installed in a recent version: %s!
+    #
+    #      $ curl https://get.volta.sh | bash
+    #
+    #    Or see the documentation: https://docs.volta.sh/guide/getting-started
+
+
+## Integrations
+
+## Example: Custom
+welcome:
+  message: Hi, thanks for using POSH!
+
+```
+
 Once initialized, you can start posh through:
 
-```bash
+```shell
 $ make shell
 ```