docs: add references from devel guide to each repo (#21)

Signed-off-by: Miguel Martinez Trivino <[email protected]>

Author: migmartri

app/artifact-cas/README.md

@@ -1,16 +1,16 @@
 # Artifact Content Addressable Storage (CAS) Proxy
 
-The artifact proxy is a **Content Addressable Storage (CAS) Proxy** that sits in front of different storage backends.
+The artifact proxy is a **Content-Addressable Storage (CAS) Proxy** that sits in front of different storage backends.
 
-Clients such as the Chainloop Control Plane or the CLI can use this proxy to make sure that **immutable uploads are performed**. Files that later, on **can only be referenced by their content digest (sha256)**.
+Clients such as the Chainloop Control Plane or the CLI use this proxy to make sure that **uploaded artifacts are immutable and uniquely identifiable by their content digest (sha256sum)**.
 
 NOTE: At the moment of this writing, only an [OCI](https://opencontainers.org/) storage backend is supported. In the future you should potentially expect Object Storage Support (i.e AWS s3) as well.
 
 ![cas](../../docs/img/cas-overview.png)
 
 The project is a [Go](https://go.dev/) service that leverages [protocol buffers](https://github.com/protocolbuffers/protobuf) and [gRPC](https://grpc.io/) for its streaming API, [wire](https://github.com/google/wire/) for dependency injection and the [Kratos framework](https://github.com/go-kratos/kratos) for additional utilities such middlewares, configuration management or error handling.
 
-The proxy API implements [a bytestream](https://pkg.go.dev/google.golang.org/api/transport/bytestream) gRPC service. This enables an efficient, and modern, streaming API for chunk based operations on top of HTTP/2.
+The proxy API implements a [bytestream gRPC service](https://pkg.go.dev/google.golang.org/api/transport/bytestream). This enables an efficient, and modern, streaming API on top of HTTP/2.
 
 Its structure contains the following top to down layers.
 
@@ -26,7 +26,7 @@ This secret backend is used to download OCI repository credentials (repository p
 
 ## AuthN/AuthZ
 
-The Artifact CAS API expects each request to contain a [JSON Web Token](https://auth0.com/docs/secure/tokens/json-web-tokens) with references to a) what operation is this token allowed to do (Download, Upload) and b) a reference to where the CAS can find the OCI credentials.
+The Artifact CAS API expects each request to contain a [JSON Web Token](https://auth0.com/docs/secure/tokens/json-web-tokens) with references to a) what operation is this token allowed to do (download or upload) and b) a reference to where the CAS can find the target OCI credentials.
 
 Currently, this token is generated by the Control Plane and used on demand. You can find the generator we use to craft those tokens [here](../../internal/robotaccount/cas/robotaccount.go).
 
@@ -36,7 +36,7 @@ Note: there are plans to support [JWKS endpoints](https://auth0.com/docs/secure/
 
 ## Runbook
 
-We leverage `make` for most development tasks. Run `make -C app/artifact-cas` to see a list of the available tasks.
+We use `make` for most development tasks. Run `make -C app/artifact-cas` to see a list of the available tasks.
 
 ### Run the project in development
 
@@ -77,7 +77,7 @@ make build
 
 ### Generate API code from protocol buffer defintions (\*.proto)
 
-We leverage buf.io to lint and generate proto files. Make sure you [install buf](https://docs.buf.build/installation) first. Once done, generating the API code is as easy as executing
+We use buf.io to lint and generate proto files. Make sure you [install buf](https://docs.buf.build/installation) first. Once done, generating the API code is as easy as executing
 
 ```
 make api

app/cli/README.md

@@ -1,6 +1,6 @@
 # Command Line Interface (CLI)
 
-This Command Line Interface (CLI) is a local client that's used for two purposes
+This Command Line Interface (CLI) is a local client that's used for two purposes:
 
 a) Operator [Management Tasks](https://docs.chainloop.dev/getting-started/workflow-definition)
 
@@ -9,15 +9,15 @@ a) Operator [Management Tasks](https://docs.chainloop.dev/getting-started/workfl
 
 b) [Attestation Crafting Process](https://docs.chainloop.dev/getting-started/attestation-crafting)
 
-- This CLI will be used in different CI/CD systems to perform the [attestation process](https://docs.chainloop.dev/getting-started/attestation-crafting)
+- Perform the [attestation process](https://docs.chainloop.dev/getting-started/attestation-crafting) inside a CI/CD system.
 
 ![cas](../../docs/img/cli-overview.png)
 
-The project is a [Go](https://go.dev/) CLI that leverages [Cobra](https://github.com/spf13/cobra) for CLI scaffolding, [Viper](https://github.com/spf13/viper) for configuration handling, [gRPC](https://grpc.io/) to communicate with both the control plane and the Artifact CAS APIs, and the [cosign](https://github.com/sigstore/cosign), [in-toto](https://github.com/in-toto/in-toto), [DSEE](https://github.com/secure-systems-lab/dsse/) and [SLSA](https://github.com/slsa-framework/slsa) projects to implement the attestation process.
+The project is a [Go](https://go.dev/) CLI that leverages [Cobra](https://github.com/spf13/cobra) for CLI scaffolding, [Viper](https://github.com/spf13/viper) for configuration handling, [gRPC](https://grpc.io/) to communicate with both the control plane and the Artifact CAS APIs, and the [cosign](https://github.com/sigstore/cosign), [in-toto](https://github.com/in-toto/in-toto), [DSEE](https://github.com/secure-systems-lab/dsse/) and [SLSA](https://github.com/slsa-framework/slsa) projects for the attestation process.
 
 ## Runbook
 
-We leverage `make` for most development tasks. Run `make -C app/cli` to see a list of the available tasks.
+We use `make` for most development tasks. Run `make -C app/cli` to see a list of the available tasks.
 
 ### Run the project in development
 
@@ -27,6 +27,8 @@ Refer to [development guide](../../devel/README.md) for more information but in
 go run app/cli/main.go --insecure
 ```
 
+> NOTE: In development a --insecure flag must be provided to talk to the local APIs
+
 ### Configure the CLI to point to the local control plane and CAS services.
 
 If you want to use this CLI pointing to a local or custom instance of Chainloop, you need to perform a config override this way.

app/controlplane/README.md

@@ -27,7 +27,7 @@ The control plane has 4 main dependencies
 
 ## Runbook
 
-We leverage `make` for most development tasks. Run `make -C app/controlplane` to see a list of the available tasks.
+We use `make` for most development tasks. Run `make -C app/controlplane` to see a list of the available tasks.
 
 ### Run the project in development
 
@@ -58,7 +58,7 @@ make build
 
 ### Generate API code from protocol buffer defintions (\*.proto)
 
-We leverage buf.io to lint and generate proto files. Make sure you [install buf](https://docs.buf.build/installation) first.
+We use buf.io to lint and generate proto files. Make sure you [install buf](https://docs.buf.build/installation) first.
 
 Once done, generating the API code is as easy as executing
 

devel/README.md

@@ -33,8 +33,8 @@ docker compose up
 
 Once you have the pre-required services up and running, you should be able to run the different Chainloop server-side components, in our case we have:
 
-- The Control Plane (`app/controlplane`)
-- The Artifact Content Addressable Storage (CAS) Proxy (`app/artifact-cas`)
+- The Control Plane [`app/controlplane`](../app/controlplane/)
+- The Artifact Content Addressable Storage (CAS) Proxy [`app/artifact-cas`](../app/artifact-cas/)
 
 These components are built using [Go](https://go.dev/), have a `Makefile` and a `make run` target for convenience.
 
@@ -43,7 +43,7 @@ These components are built using [Go](https://go.dev/), have a `Makefile` and a
 
 ### 4 - Using the CLI pointing to the local environment
 
-The Command line interface (CLI) is used for both a) operate on the control plane and b) run the attestation process on your CI/CD.
+The [Command line interface (CLI)](../app/cli/) is used for both a) operate on the control plane and b) run the attestation process on your CI/CD.
 
 You can run it by executing `go run app/cli/main.go`